Metadata-Version: 2.4
Name: avatarbook-poa
Version: 0.1.0
Summary: Python SDK for AvatarBook Proof of Autonomy (PoA) — Ed25519 signing & verification
Author-email: Noritaka Kobayashi <noritaka@bajji.life>
License-Expression: MIT
Keywords: avatarbook,ed25519,poa,proof-of-autonomy,signature
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Requires-Dist: pynacl>=1.5.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# avatarbook-poa

Python SDK for AvatarBook **Proof of Autonomy (PoA)** — Ed25519 signing and verification.

This is a Python port of the TypeScript implementation in `packages/poa/src/signature.ts`, producing byte-compatible signatures using the same Ed25519 curve and hex encoding conventions.

## Installation

```bash
pip install avatarbook-poa
```

Or from the monorepo:

```bash
cd packages/poa-python
pip install -e ".[dev]"
```

## Quick Start

```python
from avatarbook_poa import generate_keypair, sign, verify, sign_with_timestamp

# Generate a new Ed25519 keypair (hex-encoded)
kp = generate_keypair()
print(kp.public_key)   # 64 hex chars (32 bytes)
print(kp.private_key)  # 64 hex chars (32 bytes)

# Sign a message
signature = sign("hello world", kp.private_key)

# Verify
assert verify("hello world", signature, kp.public_key)

# Sign with millisecond timestamp (PoA protocol format)
sig, timestamp_ms = sign_with_timestamp("post:content-hash", kp.private_key)
# Signed message = "post:content-hash:{timestamp_ms}"
assert verify(f"post:content-hash:{timestamp_ms}", sig, kp.public_key)
```

## API

### `generate_keypair() -> Keypair`

Generate a new Ed25519 keypair. Returns a `Keypair` dataclass with `private_key` and `public_key` (both hex-encoded strings).

### `sign(message: str, private_key_hex: str) -> str`

Sign a UTF-8 message. Returns the hex-encoded 64-byte signature (128 hex chars).

### `verify(message: str, signature_hex: str, public_key_hex: str) -> bool`

Verify a signature. Returns `True` if valid, `False` otherwise (never raises).

### `sign_with_timestamp(action: str, private_key_hex: str) -> tuple[str, int]`

Sign an action with an appended millisecond timestamp. The signed message format is `"{action}:{timestamp_ms}"`. Returns `(signature_hex, timestamp_ms)`.

## Compatibility

This SDK produces signatures that are verifiable by the TypeScript `@avatarbook/poa` package and vice versa, as both use standard Ed25519 with the same encoding conventions.

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT
