agent-receipts 0.2.1__py3-none-any.whl

agent_receipts-0.2.1.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: agent-receipts
+Version: 0.2.1
+Summary: Python SDK for the Action Receipts protocol
+Project-URL: Homepage, https://github.com/agnt-rcpt/sdk-py
+Project-URL: Repository, https://github.com/agnt-rcpt/sdk-py
+Project-URL: Issues, https://github.com/agnt-rcpt/sdk-py/issues
+Project-URL: Spec, https://github.com/agnt-rcpt/spec
+Author: Otto Jongerius
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,ai,audit,receipts,verifiable-credentials
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# attest-protocol
+
+### Python SDK for the Action Receipts protocol
+
+[![PyPI](https://img.shields.io/pypi/v/attest-protocol)](https://pypi.org/project/attest-protocol/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![CI](https://github.com/attest-protocol/attest-py/actions/workflows/ci.yml/badge.svg)](https://github.com/attest-protocol/attest-py/actions/workflows/ci.yml)
+
+---
+
+Create, sign, hash-chain, store, and verify cryptographically signed audit trails for AI agent actions.
+
+[Spec](https://github.com/attest-protocol/spec) &bull; [TypeScript SDK](https://github.com/attest-protocol/attest-ts) &bull; [Reference Implementation](https://github.com/ojongerius/attest)
+
+</div>
+
+---
+
+## Why receipts?
+
+If you're building with AI agents, you're probably already logging what they do. Receipts go further: they're **cryptographically signed, hash-chained records** that can't be quietly altered after the fact — and they follow a standard format that works across languages, agents, and systems.
+
+Here's where that matters in practice:
+
+- **Post-incident review** — An agent ran overnight and something broke. The receipt chain shows exactly which actions it took, in what order, and whether each succeeded or failed — with cryptographic proof the log hasn't been tampered with after the fact.
+
+- **Compliance and audit** — Regulated environments require evidence of what systems did and why. Receipts are W3C Verifiable Credentials with Ed25519 signatures, giving auditors a tamper-evident trail they can independently verify.
+
+- **Safer autonomous agents** — Agents can query their own audit trail mid-session. Before taking a high-risk action, an agent can check what it has already done and whether previous steps succeeded, enabling self-correcting workflows.
+
+- **Multi-agent trust** — When agents collaborate, receipts serve as proof of prior actions. Agent B can verify that Agent A actually completed step 1 before proceeding to step 2, without trusting a shared log.
+
+- **Usage tracking** — Every action is classified by type and risk level, giving you a structured breakdown of what agents spent their time on.
+
+### Beyond local storage
+
+The protocol is designed for receipts to travel — publishing to a shared ledger, forwarding to a compliance system, or exchanging between agents as proof of prior actions. Receipts are portable W3C Verifiable Credentials, but where they go is always under the user's control.
+
+---
+
+## Install
+
+```sh
+pip install attest-protocol
+```
+
+## Quick start
+
+### Create and sign a receipt
+
+```python
+from attest_protocol import (
+    create_receipt,
+    generate_key_pair,
+    hash_receipt,
+    sign_receipt,
+    CreateReceiptInput,
+    Chain,
+    Issuer,
+    Outcome,
+    Principal,
+)
+from attest_protocol.receipt.create import ActionInput
+
+# Generate an Ed25519 key pair
+keys = generate_key_pair()
+
+# Create an unsigned receipt
+unsigned = create_receipt(CreateReceiptInput(
+    issuer=Issuer(id="did:agent:my-agent"),
+    principal=Principal(id="did:user:alice"),
+    action=ActionInput(
+        type="filesystem.file.read",
+        risk_level="low",
+    ),
+    outcome=Outcome(status="success"),
+    chain=Chain(
+        sequence=1,
+        previous_receipt_hash=None,
+        chain_id="chain_session-1",
+    ),
+))
+
+# Sign and hash
+receipt = sign_receipt(unsigned, keys.private_key, "did:agent:my-agent#key-1")
+receipt_hash = hash_receipt(receipt)
+```
+
+### Verify a receipt
+
+```python
+from attest_protocol import verify_receipt
+
+valid = verify_receipt(receipt, keys.public_key)
+print(f"Signature valid: {valid}")  # True
+```
+
+### Verify a chain
+
+```python
+from attest_protocol import verify_chain
+
+# Verify a list of receipts (e.g. [receipt] from the example above)
+result = verify_chain([receipt], keys.public_key)
+print(f"Chain valid: {result.valid}")
+print(f"Receipts verified: {result.length}")
+if not result.valid:
+    print(f"Broken at index: {result.broken_at}")
+```
+
+### Action taxonomy
+
+The standardized action taxonomy (action types and risk levels) is defined in the
+[protocol specification](https://github.com/attest-protocol/spec/tree/main/spec/taxonomy).
+Taxonomy classification will be added in a future milestone (M3).
+
+## What is an Action Receipt?
+
+A [W3C Verifiable Credential](https://www.w3.org/TR/vc-data-model-2.0/) signed with Ed25519, recording:
+
+| Field | What it captures |
+|:---|:---|
+| **Action** | What happened, classified by a [standardized taxonomy](https://github.com/attest-protocol/spec/tree/main/spec/taxonomy) |
+| **Principal** | Who authorized it (human or organization) |
+| **Issuer** | Which agent performed it |
+| **Outcome** | Success/failure, reversibility, undo method |
+| **Chain** | SHA-256 hash link to the previous receipt (tamper-evident) |
+| **Privacy** | Parameters are hashed, never stored in plaintext |
+
+## API reference
+
+### Receipt creation and signing
+
+```python
+from attest_protocol import (
+    create_receipt,       # Build an unsigned receipt from input fields
+    generate_key_pair,    # Ed25519 key pair (PEM-encoded)
+    sign_receipt,         # Sign with Ed25519Signature2020 proof
+    verify_receipt,       # Verify a receipt's signature
+)
+```
+
+### Hashing and canonicalization
+
+```python
+from attest_protocol import (
+    canonicalize,         # RFC 8785 JSON canonicalization
+    hash_receipt,         # Hash receipt (excluding proof) -> "sha256:<hex>"
+    sha256,               # Hash arbitrary data -> "sha256:<hex>"
+)
+```
+
+### Chain verification
+
+```python
+from attest_protocol import (
+    verify_chain,         # Verify signatures, hash links, and sequence numbering
+)
+```
+
+### Types (Pydantic v2 models)
+
+```python
+from attest_protocol import (
+    ActionReceipt,        # Signed receipt with proof
+    UnsignedActionReceipt,  # Receipt before signing
+    Action, ActionTarget, Authorization, Chain,
+    CredentialSubject, Intent, Issuer, Operator,
+    Outcome, Principal, Proof, StateChange,
+)
+```
+
+### Subpackage imports
+
+```python
+from attest_protocol.receipt import create_receipt, sign_receipt
+from attest_protocol.receipt.hash import canonicalize
+from attest_protocol.receipt.types import CONTEXT, CREDENTIAL_TYPE
+```
+
+### TypeScript SDK compatibility
+
+camelCase aliases are available for users coming from the TS SDK:
+
+```python
+from attest_protocol import (
+    createReceipt,    # = create_receipt
+    generateKeyPair,  # = generate_key_pair
+    signReceipt,      # = sign_receipt
+    verifyReceipt,    # = verify_receipt
+    hashReceipt,      # = hash_receipt
+    verifyChain,      # = verify_chain
+)
+```
+
+## Cross-language compatibility
+
+This SDK produces **byte-identical** output to [`@attest-protocol/attest-ts`](https://github.com/attest-protocol/attest-ts):
+
+- RFC 8785 canonical JSON matches exactly
+- SHA-256 hashes are identical
+- Ed25519 signatures from either SDK verify in the other
+
+Cross-language compatibility is verified by test vectors generated from the TypeScript SDK.
+
+## Project structure
+
+```
+src/attest_protocol/
+  receipt/
+    types.py       # Pydantic models for all receipt types
+    create.py      # Receipt creation with auto-generated IDs
+    signing.py     # Ed25519 signing and verification
+    hash.py        # RFC 8785 canonicalization + SHA-256
+    chain.py       # Chain verification
+```
+
+## Development
+
+```sh
+uv sync --all-extras
+uv run pytest              # run tests
+uv run ruff check .        # lint
+uv run ruff format .       # format
+uv run pyright             # type check
+```
+
+| | |
+|:---|:---|
+| **Language** | Python 3.11+ |
+| **Types** | Pydantic v2, pyright strict mode |
+| **Linting** | ruff |
+| **Testing** | pytest |
+| **Dependencies** | `pydantic>=2.0`, `cryptography>=41.0` |
+
+## Ecosystem
+
+| Repository | Description |
+|:---|:---|
+| [attest-protocol/spec](https://github.com/attest-protocol/spec) | Protocol specification, JSON Schemas, canonical taxonomy |
+| [attest-protocol/attest-ts](https://github.com/attest-protocol/attest-ts) | TypeScript SDK ([npm](https://www.npmjs.com/package/@attest-protocol/attest-ts)) |
+| **attest-protocol/attest-py** (this package) | Python SDK |
+| [ojongerius/attest](https://github.com/ojongerius/attest) | MCP proxy + CLI (reference implementation) |
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

agent_receipts-0.2.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+attest_protocol/__init__.py,sha256=kwKaNQHb7xg5-tanXkI-Z4dfYcoU5_vL3fe2YKGyMIc,3343
+attest_protocol/_version.py,sha256=w9Iw7QVvd8lme2wKwEbCo5IgetVjSfFBOOYAcA_Q0Ns,18
+attest_protocol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+attest_protocol/receipt/__init__.py,sha256=l1RPZgdyALgAJ49qWSoCuz0FJulfnOIMh6KMgvJl3cs,1362
+attest_protocol/receipt/chain.py,sha256=6pL26ksKoHTW0nyHbYd-IGsVQjVTuP9mNg1w3qKPDrc,2661
+attest_protocol/receipt/create.py,sha256=kEvk7sj534nT3W7ssj8qQ6SGE15p1Hw_Z9IaAeRUS0s,2932
+attest_protocol/receipt/hash.py,sha256=gB8tCvTH2rAleK7GU0mli2Mq85yDVRSUs5ApJVUTh_g,3697
+attest_protocol/receipt/signing.py,sha256=vT62mnnqOxOMhU3ZgvEf6bzvwd2IDYYz8GhsHfP0fDc,4226
+attest_protocol/receipt/types.py,sha256=c9ILfSSfSrffn9-XEs232vk_exyNjSB-FJFFWg0v7dE,3588
+attest_protocol/store/__init__.py,sha256=i50VW5hkZeVNInLOUfL2r2rgqAlZs2hnR2mxbww_DwU,364
+attest_protocol/store/store.py,sha256=BuU_EI7OgcmaZeOS1wHt-vXOgwR4yYSDO4XHrzwamLM,7164
+attest_protocol/store/verify.py,sha256=kzz_3pZCklTivAeDa1SmqFLhyLXuc77FTy9332S02FM,587
+attest_protocol/taxonomy/__init__.py,sha256=M2DLT_4mnVOlblPbVlPz9Z_7TUgWdObAnpjbzRziRR8,791
+attest_protocol/taxonomy/actions.py,sha256=LKgFV_yrbtsfv4LJSZBnkNpIhZ3HJW9GlZDB7QIFYEU,2949
+attest_protocol/taxonomy/classify.py,sha256=lZR6Dv2z59vXkEpjSPayIr_oP5B1hW5d2ZS93xCbt3s,1058
+attest_protocol/taxonomy/config.py,sha256=1NzzNo9U407xEKDnzF3VztOarlamlj_N9dbTmZ-9BA4,1973
+attest_protocol/taxonomy/types.py,sha256=e70VsA-YMLqJfbJPmsRo2i0Ho4LyQv8HtiPmpg3AZR4,512
+agent_receipts-0.2.1.dist-info/METADATA,sha256=9KwactIRXDzVpfAgmJma1HtvV3CbqsJft00EM1NPMV8,9559
+agent_receipts-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agent_receipts-0.2.1.dist-info/licenses/LICENSE,sha256=ZNP4Wy2jzAlWYAvfws5JqirwxpamE_Xo-BZfjgZ39i0,1072
+agent_receipts-0.2.1.dist-info/RECORD,,

agent_receipts-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_receipts-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 attest-protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

attest_protocol/__init__.py

@@ -0,0 +1,139 @@
+"""Python SDK for the Action Receipts protocol."""
+
+from attest_protocol._version import VERSION
+from attest_protocol.receipt.chain import (
+    ChainVerification,
+    ReceiptVerification,
+    verify_chain,
+)
+from attest_protocol.receipt.create import CreateReceiptInput, create_receipt
+from attest_protocol.receipt.hash import canonicalize, hash_receipt, sha256
+from attest_protocol.receipt.signing import (
+    KeyPair,
+    generate_key_pair,
+    sign_receipt,
+    verify_receipt,
+)
+from attest_protocol.receipt.types import (
+    CONTEXT,
+    CREDENTIAL_TYPE,
+    Action,
+    ActionReceipt,
+    ActionTarget,
+    Authorization,
+    Chain,
+    CredentialSubject,
+    Intent,
+    Issuer,
+    Operator,
+    Outcome,
+    Principal,
+    Proof,
+    StateChange,
+    UnsignedActionReceipt,
+)
+from attest_protocol.store.store import (
+    ReceiptQuery,
+    ReceiptStore,
+    StoreStats,
+    open_store,
+)
+from attest_protocol.store.verify import verify_stored_chain
+from attest_protocol.taxonomy.actions import (
+    ALL_ACTIONS,
+    FILESYSTEM_ACTIONS,
+    SYSTEM_ACTIONS,
+    UNKNOWN_ACTION,
+    get_action_type,
+    resolve_action_type,
+)
+from attest_protocol.taxonomy.classify import ClassificationResult, classify_tool_call
+from attest_protocol.taxonomy.config import load_taxonomy_config
+from attest_protocol.taxonomy.types import ActionTypeEntry, TaxonomyMapping
+
+# camelCase aliases for users coming from the TypeScript SDK
+createReceipt = create_receipt
+generateKeyPair = generate_key_pair
+signReceipt = sign_receipt
+verifyReceipt = verify_receipt
+hashReceipt = hash_receipt
+verifyChain = verify_chain
+openStore = open_store
+verifyStoredChain = verify_stored_chain
+classifyToolCall = classify_tool_call
+getActionType = get_action_type
+resolveActionType = resolve_action_type
+loadTaxonomyConfig = load_taxonomy_config
+
+# RECEIPT_VERSION is the receipt schema version (from types), not the package version
+from attest_protocol.receipt.types import VERSION as RECEIPT_VERSION  # noqa: E402
+
+__all__ = [
+    # Version
+    "VERSION",
+    "RECEIPT_VERSION",
+    # Types
+    "Action",
+    "ActionReceipt",
+    "ActionTarget",
+    "Authorization",
+    "Chain",
+    "CredentialSubject",
+    "Intent",
+    "Issuer",
+    "Operator",
+    "Outcome",
+    "Principal",
+    "Proof",
+    "StateChange",
+    "UnsignedActionReceipt",
+    # Constants
+    "CONTEXT",
+    "CREDENTIAL_TYPE",
+    # Creation
+    "CreateReceiptInput",
+    "create_receipt",
+    "createReceipt",
+    # Hashing
+    "canonicalize",
+    "hash_receipt",
+    "hashReceipt",
+    "sha256",
+    # Signing
+    "KeyPair",
+    "generate_key_pair",
+    "generateKeyPair",
+    "sign_receipt",
+    "signReceipt",
+    "verify_receipt",
+    "verifyReceipt",
+    # Chain
+    "ChainVerification",
+    "ReceiptVerification",
+    "verify_chain",
+    "verifyChain",
+    # Store
+    "ReceiptQuery",
+    "ReceiptStore",
+    "StoreStats",
+    "open_store",
+    "openStore",
+    "verify_stored_chain",
+    "verifyStoredChain",
+    # Taxonomy
+    "ALL_ACTIONS",
+    "ActionTypeEntry",
+    "ClassificationResult",
+    "FILESYSTEM_ACTIONS",
+    "SYSTEM_ACTIONS",
+    "TaxonomyMapping",
+    "UNKNOWN_ACTION",
+    "classify_tool_call",
+    "classifyToolCall",
+    "get_action_type",
+    "getActionType",
+    "load_taxonomy_config",
+    "loadTaxonomyConfig",
+    "resolve_action_type",
+    "resolveActionType",
+]

attest_protocol/_version.py

@@ -0,0 +1 @@
+VERSION = "0.2.0"

attest_protocol/receipt/__init__.py

@@ -0,0 +1,70 @@
+from attest_protocol.receipt.chain import (
+    ChainVerification,
+    ReceiptVerification,
+    verify_chain,
+)
+from attest_protocol.receipt.create import CreateReceiptInput, create_receipt
+from attest_protocol.receipt.hash import canonicalize, hash_receipt, sha256
+from attest_protocol.receipt.signing import (
+    KeyPair,
+    generate_key_pair,
+    sign_receipt,
+    verify_receipt,
+)
+from attest_protocol.receipt.types import (
+    CONTEXT,
+    CREDENTIAL_TYPE,
+    VERSION,
+    Action,
+    ActionReceipt,
+    ActionTarget,
+    Authorization,
+    Chain,
+    CredentialSubject,
+    Intent,
+    Issuer,
+    Operator,
+    Outcome,
+    Principal,
+    Proof,
+    StateChange,
+    UnsignedActionReceipt,
+)
+
+__all__ = [
+    # Types
+    "Action",
+    "ActionReceipt",
+    "ActionTarget",
+    "Authorization",
+    "Chain",
+    "CredentialSubject",
+    "Intent",
+    "Issuer",
+    "Operator",
+    "Outcome",
+    "Principal",
+    "Proof",
+    "StateChange",
+    "UnsignedActionReceipt",
+    # Constants
+    "CONTEXT",
+    "CREDENTIAL_TYPE",
+    "VERSION",
+    # Creation
+    "CreateReceiptInput",
+    "create_receipt",
+    # Hashing
+    "canonicalize",
+    "hash_receipt",
+    "sha256",
+    # Signing
+    "KeyPair",
+    "generate_key_pair",
+    "sign_receipt",
+    "verify_receipt",
+    # Chain
+    "ChainVerification",
+    "ReceiptVerification",
+    "verify_chain",
+]

attest_protocol/receipt/chain.py

@@ -0,0 +1,95 @@
+"""Chain verification — validate receipt chains for integrity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from attest_protocol.receipt.hash import hash_receipt
+from attest_protocol.receipt.signing import verify_receipt
+
+if TYPE_CHECKING:
+    from attest_protocol.receipt.types import ActionReceipt
+
+
+@dataclass
+class ReceiptVerification:
+    """Result of verifying a single receipt in a chain."""
+
+    index: int
+    receipt_id: str
+    signature_valid: bool
+    hash_link_valid: bool
+    sequence_valid: bool
+
+
+@dataclass
+class ChainVerification:
+    """Result of verifying an entire chain."""
+
+    valid: bool
+    length: int
+    receipts: list[ReceiptVerification] = field(default_factory=list)
+    broken_at: int = -1
+
+
+def verify_chain(
+    receipts: list[ActionReceipt],
+    public_key: str,
+) -> ChainVerification:
+    """Verify a chain of signed receipts.
+
+    Checks for each receipt:
+    1. Ed25519 signature validity
+    2. Hash linkage: previous_receipt_hash matches SHA-256 of prior receipt
+    3. Sequence numbers are strictly incrementing
+
+    Receipts must be provided in chain order (by sequence number).
+    """
+    if not receipts:
+        return ChainVerification(valid=True, length=0)
+
+    results: list[ReceiptVerification] = []
+    broken_at = -1
+    previous: ActionReceipt | None = None
+
+    for i, receipt in enumerate(receipts):
+        chain = receipt.credentialSubject.chain
+
+        signature_valid = verify_receipt(receipt, public_key)
+
+        if previous is None:
+            hash_link_valid = chain.previous_receipt_hash is None
+        else:
+            previous_hash = hash_receipt(previous)
+            hash_link_valid = chain.previous_receipt_hash == previous_hash
+
+        current_sequence = chain.sequence
+        if previous is None:
+            sequence_valid = current_sequence >= 1
+        else:
+            prev_sequence = previous.credentialSubject.chain.sequence
+            sequence_valid = current_sequence == prev_sequence + 1
+
+        verification = ReceiptVerification(
+            index=i,
+            receipt_id=receipt.id,
+            signature_valid=signature_valid,
+            hash_link_valid=hash_link_valid,
+            sequence_valid=sequence_valid,
+        )
+        results.append(verification)
+
+        if broken_at == -1 and (
+            not signature_valid or not hash_link_valid or not sequence_valid
+        ):
+            broken_at = i
+
+        previous = receipt
+
+    return ChainVerification(
+        valid=broken_at == -1,
+        length=len(receipts),
+        receipts=results,
+        broken_at=broken_at,
+    )