Metadata-Version: 2.4
Name: tn-proto
Version: 2026.9.13b3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security :: Cryptography
Requires-Dist: pyyaml>=6.0
Requires-Dist: cryptography>=41.0
Requires-Dist: joserfc>=1.0
Requires-Dist: typing-extensions>=4.0
Requires-Dist: persist-queue>=1.0
Requires-Dist: pathvalidate>=3.0
Requires-Dist: mnemonic>=0.21
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: base58>=2.1
Requires-Dist: pynacl>=1.5
Requires-Dist: pydantic>=2
Requires-Dist: confluent-kafka>=2.3 ; extra == 'all'
Requires-Dist: databricks-sql-connector>=3.0 ; extra == 'all'
Requires-Dist: databricks-sdk>=0.20 ; extra == 'all'
Requires-Dist: boto3>=1.34 ; extra == 'all'
Requires-Dist: websocket-client>=1.7 ; extra == 'all'
Requires-Dist: drain3>=0.9 ; extra == 'all'
Requires-Dist: pytest>=7 ; extra == 'all'
Requires-Dist: pytest-cov>=4 ; extra == 'all'
Requires-Dist: databricks-sql-connector>=3.0 ; extra == 'delta'
Requires-Dist: databricks-sdk>=0.20 ; extra == 'delta'
Requires-Dist: drain3>=0.9 ; extra == 'exhaust'
Requires-Dist: websocket-client>=1.7 ; extra == 'firehose'
Requires-Dist: confluent-kafka>=2.3 ; extra == 'kafka'
Requires-Dist: boto3>=1.34 ; extra == 's3'
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: pytest-cov>=4 ; extra == 'test'
Provides-Extra: all
Provides-Extra: delta
Provides-Extra: exhaust
Provides-Extra: firehose
Provides-Extra: kafka
Provides-Extra: s3
Provides-Extra: test
Summary: TN protocol: signed data, encrypted groups, and governed workflows
Keywords: cryptography,broadcast-encryption,attestation,governance
Author-email: cyaxios contributors <dev@cyaxios.com>
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/cyaxios/tn-proto/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/cyaxios/tn-proto
Project-URL: Issues, https://github.com/cyaxios/tn-proto/issues
Project-URL: Repository, https://github.com/cyaxios/tn-proto

# TN-Proto

Create encrypted, signed data objects in Python. Each object carries a use contract and retains the sources your application records as it works with the data.

Start with a greeting. The examples below build on one another, one operation at a time.

## Install

```bash
python -m pip install "tn-proto==2026.9.13b3"
```

Python 3.10 or newer. Linux x86-64 and Windows x64 wheels include the Rust implementation.

## 1. Start a session

Save the sample [agents.md](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/python/examples/getting_started/agents.md) in your working folder. It contains a contract named `hello.message` for displaying greetings.

Run the following Python snippets in order, in the same process:

```python
from pathlib import Path
import tn

session = tn.Session(Path("agents.md").read_text(encoding="utf-8"))
policy = session.policy("hello.message")
```

The session has its own identity and encryption keys. This example creates fresh keys and uses them for the whole walkthrough.

## 2. Create an object and read a field

```python
message = session.create({"message": "Hello, world!"}, policy)
print(message.get("message"))
```

```text
Hello, world!
```

`create` returns a data object with an initial signed copy. `get` reads a field.

## 3. Change the field

```python
message.set("message", "Hello again!")
print(message.get("message"))
```

```text
Hello again!
```

The working data has changed. The previous signed copy still contains the original greeting.

## 4. Define the approval rule

Before opening or publishing data, the application makes a decision. For this example, accept our own writer and exactly the contract we selected:

```python
def trusted_message(context):
    return (
        context.writer == session.did
        and len(context.policies) == 1
        and context.policies[0].matches_contract(policy)
    )
```

TN supplies the writer and carried contracts to this function. The application provides the rule; the text in `agents.md` does not execute itself.

## 5. Seal the changed object

Name the application, purpose, and operation with `UseContext`. Then approve this publication for its intended destination:

```python
publish_use = tn.UseContext("hello", "greeting", "publish")
publication = message.seal(
    use=publish_use, to="local-reader",
    decide=lambda context: trusted_message(context)
    and context.use_context == publish_use
    and context.destination == "local-reader",
)
```

`seal` evaluates the decision and creates a new encrypted, signed publication. It keeps the contract and the reference to the preceding version. The destination is part of the approval; your application chooses how to deliver the bytes.

## 6. Save and read the publication

```python
publication.write("greeting.tn")
saved = tn.GovernedObject.read("greeting.tn")
```

`write` saves the signed bytes. `read` verifies the saved publication; its business fields remain encrypted.

## 7. Unseal it for an approved use

The same session can open its saved publication. Approve the writer, contract, and requested reading use:

```python
read_use = tn.UseContext("hello", "greeting", "read")
received = session.unseal(
    saved, use=read_use,
    decide=lambda context: trusted_message(context)
    and context.use_context == read_use,
)
print(received.get("message"))
```

```text
Hello again!
```

`unseal` verifies the publication, runs the approval rule, and decrypts the message using the session's keys. A refused decision or a missing key stops it from returning the business data.

Close the session when finished:

```python
session.close()
```

The complete walkthrough is available as [hello.py](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/python/examples/getting_started/hello.py), alongside its policy file.

## Build on this example

- **Reuse the same rules:** configure a [workflow](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/docs/GOVERNED_PYTHON_API.md#configure-input-output-and-attachment) once, then call `work.unseal(...)` and `work.seal(...)` in application code.
- **Use separate senders and readers:** the [bank/vendor example](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/python/examples/bank_vendor.py) separates identities and group keys, adds inputs totaling 35, and returns a report with the bank and vendor contracts.
- **Keep keys between runs:** the [persistent-key examples](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/python/examples/persistent_keys/README.md) cover separate setup, publishing, and reading processes. [Providers](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/docs/GOVERNED_PYTHON_API.md#providers) connect application identity, keys, and governance.
- **Apply enterprise patterns:** the [15 examples from the book](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/python/examples/enterprise/README.md) cover request/reply, aggregation, outbox/inbox, pipelines, caches, and more.

## API and reference

The [Python API guide](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/docs/GOVERNED_PYTHON_API.md) covers the full operation signatures, groups, decisions, providers, policy revisions, datasets, and lineage. The [object-operation reference](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/docs/TN_VERBS_API.md) lists the verbs and their behavior.

See the [release notes](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/CHANGELOG.md), [BTN cover implementation](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/docs/BTN_COVER.md), and [paper reproducibility review](https://github.com/cyaxios/tn-proto/blob/python-v2026.9.13b3/docs/PAPER_REPRODUCIBILITY.md) for implementation and research details.

## License

Dual-licensed under the MIT License or the Apache License, Version 2.0.

