Metadata-Version: 2.4
Name: entpoind-verify
Version: 0.1.0
Summary: Offline verification of Entpoind Tools receipts and VerifiableArtifact bundles: Ed25519 over RFC 8785 canonical JSON, plus Merkle inclusion proofs. Standard library only.
Project-URL: Homepage, https://entpoind.com/docs/sdks
Project-URL: Documentation, https://entpoind.com/docs/verification
Author: Avonao, Inc.
License-Expression: MIT
License-File: LICENSE
Keywords: ed25519,entpoind,jcs,merkle,receipt,rfc8785,tools,verification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# entpoind-verify

Offline verification of **Entpoind Tools** receipts and **VerifiableArtifact**
bundles. Python 3.9 or later, **standard library only**: it carries its own
pure-Python Ed25519 verifier, so nothing outside these files is trusted.

```bash
pip install entpoind-verify
```

> **Not on PyPI yet** (checked 2026-10-29: `pypi.org/pypi/entpoind-verify` answers 404), and the customer docs
> (`content/tools-docs/sdks.mdx`) say the Python verifier does not exist. Remove this note when the package is
> published; until then the command above fails, and the Python snippet in the docs is the way to verify.

```python
from entpoind_verify import verify_receipt_online

result = verify_receipt_online(receipt_json)
if result.ok:
    print("signed at", result.signed_at, "by key", result.signature_key_id)
else:
    print("not verified:", result.reason)
```

`receipt_json` can be the receipt dict, its JSON text, or the `{"receipt": …}`
wrapper the API returns.

## What it verifies

- **Tools receipts**: the signed envelope every Tools call returns, of every
  receipt `type` (`agent.call`, `content.attest`, `monitor.http`,
  `heartbeat.attest`, …). Scheduled-watch digest receipts verify the same way.
- **VerifiableArtifact envelopes and bundles**: the signature, and, when a bundle
  carries an `anchor`, that the artifact is included under the anchored Merkle
  root.

The signature is Ed25519 over the **RFC 8785 (JCS)** canonical form of the
envelope minus `signature`. Public keys come from the published JWK Set at
`https://entpoind.com/.well-known/tools-keys.json`. For air-gapped checks, save
that file and pass its `keys` to `verify_receipt`.

## API

| Function | Purpose |
|---|---|
| `verify_receipt(input, keys)` | Verify a receipt against keys you supply. No network. |
| `verify_receipt_online(input, url?)` | Fetch the published keys, then verify. |
| `fetch_tools_keys(url?)` | Fetch the published JWK Set and keep its Ed25519 keys. |
| `verify_artifact(input, keys)` | Verify a standalone artifact envelope. |
| `verify_bundle(input, keys)` | Signature, plus Merkle inclusion when anchored. |
| `verify_merkle_inclusion(leaf, proof, root)` | Fold an inclusion proof locally. |
| `merkle_leaf_hash(leaf)` | The domain-separated Merkle leaf hash. |
| `canonical_jcs(value)` | The RFC 8785 canonical string. |
| `verify_signature(key, message, signature)` | The raw Ed25519 check, as a boolean. |
| `ed25519_supported()` | Always `True`; present for parity with `@entpoind/verify`. |

Every `verify_*` function returns a `Verification` with `ok`, `reason`,
`signed_at`, `signature_key_id`, `kind` (artifacts and bundles) and `anchored`
(bundles). They never raise on hostile input. `fetch_tools_keys` and
`verify_receipt_online` raise when the keys cannot be fetched, so "could not
check" is never reported as a verdict.

Only keys with `kty: "OKP"` and `crv: "Ed25519"` are ever used, whatever the
key list you pass holds.

## Failure reasons

| `reason` | Meaning |
|---|---|
| `malformed_envelope` | Not a complete receipt or artifact. |
| `unknown_key` | `signatureKeyId` matches no Ed25519 key in the set. Refresh the keys; if it is still missing, the document was not signed by Entpoind. |
| `bad_signature` | The signature does not match the canonical bytes: the document was altered, or is not Entpoind's. |
| `unsupported_runtime` | Shared with `@entpoind/verify`, where it means the runtime has no Ed25519. This package always can verify, so it never reports it. |
| `not_in_anchored_root` | Bundles only: the signature is valid but the Merkle proof does not reach the anchored root. |

A bundle without an anchor verifies with `anchored=False`; that is a valid
result, not a failure. Merkle siblings and the root must be 64 hex digits.
A bundle's `leafHash` is the plain SHA-256 of the leaf string, an index id;
verification does not use it.

## Checking the math yourself

- `entpoind_verify/ed25519.py` is the RFC 8032 verification equation.
- `entpoind_verify/canonical_json.py` is JCS, including ECMAScript number layout.
- The npm package `@entpoind/verify` gives the same verdict, with the same
  reasons, for the same input.

## Documentation

Receipt format, verification procedure and key rotation:
<https://entpoind.com/docs/verification>.

## License

MIT © 2026 Avonao, Inc.
