atcn 1.3.0__tar.gz

atcn-1.3.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

atcn-1.3.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: atcn
+Version: 1.3.0
+Summary: Python SDK for the Agent Transaction Closure Network: canonical JSON, Ed25519 event signing, webhook verification, API client, Agent Work Subledger
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/fadnisnikhil/atcn
+Project-URL: Source, https://github.com/fadnisnikhil/atcn/tree/main/packages/sdk-python
+Project-URL: Issues, https://github.com/fadnisnikhil/atcn/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# atcn (Python SDK)
+
+The ATCN Python SDK. It covers:
+
+- **Signing.** RFC 8785 canonical JSON, Ed25519 signing, and obligation event signing with `EventSigner`.
+- **Webhooks.** `verify_webhook` and `sign_webhook`.
+- **API clients.** `AtcnClient` is for the clearing network. `SubledgerClient` and `CaptureQueue` record tasks, delegations and charges. `ReceiptLinkClient` is for providers.
+- **Provider response statements.** `build_response_statement`, `sign_statement` and `verify_statement_signature`.
+
+It passes the same signing test vectors as the TypeScript SDK.
+
+```bash
+pip install atcn
+```
+
+```python
+from atcn import canonicalize, generate_key_pair, sign_payload, verify_payload
+
+canonicalize({"b": 1, "a": 2})  # '{"a":2,"b":1}'
+private_key, public_key = generate_key_pair()
+signed = sign_payload({"hello": "world"}, "key_1", 1, private_key)
+assert verify_payload(signed, public_key)
+```
+
+The API clients need an ATCN API at `base_url`. The hosted API is not open for signup yet.
+
+The Python SDK does not verify task closures or receipts. Use `npx @atcn/verify-cli` or the TypeScript SDK for that.
+
+`python -m atcn init` records whether this machine shares anonymous usage metrics. Reporting is off by default and needs `ATCN_USAGE_URL`; see the [usage data documentation](https://github.com/fadnisnikhil/atcn/blob/main/docs/USAGE_DATA.md).
+
+Apache-2.0.

atcn-1.3.0/README.md

@@ -0,0 +1,31 @@
+# atcn (Python SDK)
+
+The ATCN Python SDK. It covers:
+
+- **Signing.** RFC 8785 canonical JSON, Ed25519 signing, and obligation event signing with `EventSigner`.
+- **Webhooks.** `verify_webhook` and `sign_webhook`.
+- **API clients.** `AtcnClient` is for the clearing network. `SubledgerClient` and `CaptureQueue` record tasks, delegations and charges. `ReceiptLinkClient` is for providers.
+- **Provider response statements.** `build_response_statement`, `sign_statement` and `verify_statement_signature`.
+
+It passes the same signing test vectors as the TypeScript SDK.
+
+```bash
+pip install atcn
+```
+
+```python
+from atcn import canonicalize, generate_key_pair, sign_payload, verify_payload
+
+canonicalize({"b": 1, "a": 2})  # '{"a":2,"b":1}'
+private_key, public_key = generate_key_pair()
+signed = sign_payload({"hello": "world"}, "key_1", 1, private_key)
+assert verify_payload(signed, public_key)
+```
+
+The API clients need an ATCN API at `base_url`. The hosted API is not open for signup yet.
+
+The Python SDK does not verify task closures or receipts. Use `npx @atcn/verify-cli` or the TypeScript SDK for that.
+
+`python -m atcn init` records whether this machine shares anonymous usage metrics. Reporting is off by default and needs `ATCN_USAGE_URL`; see the [usage data documentation](https://github.com/fadnisnikhil/atcn/blob/main/docs/USAGE_DATA.md).
+
+Apache-2.0.

atcn-1.3.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atcn"
+version = "1.3.0"
+description = "Python SDK for the Agent Transaction Closure Network: canonical JSON, Ed25519 event signing, webhook verification, API client, Agent Work Subledger"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["cryptography>=42"]
+
+[project.urls]
+Homepage = "https://github.com/fadnisnikhil/atcn"
+Source = "https://github.com/fadnisnikhil/atcn/tree/main/packages/sdk-python"
+Issues = "https://github.com/fadnisnikhil/atcn/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

atcn-1.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

atcn-1.3.0/src/atcn/__init__.py

@@ -0,0 +1,60 @@
+"""ATCN Python SDK."""
+
+from .canonical import canonicalize
+from .client import SDK_HEADER, SDK_VERSION, AtcnApiError, AtcnClient
+from .crypto import (
+    digest_of,
+    generate_key_pair,
+    public_key_from_private,
+    sha256_digest,
+    sign_payload,
+    verify_payload,
+)
+from .events import EventSigner, EvidenceInput, acceptance_data, evidence_envelope, utc_now
+from .ids import new_id
+from .subledger import (
+    CaptureQueue,
+    ReceiptLinkClient,
+    SubledgerClient,
+    build_response_statement,
+    countersign_payload,
+    ext,
+    sign_statement,
+    stable_key,
+    verify_countersignature,
+    verify_statement_signature,
+)
+from .webhooks import WEBHOOK_SIGNATURE_HEADER, sign_webhook, verify_webhook
+
+__all__ = [
+    "SDK_HEADER",
+    "SDK_VERSION",
+    "AtcnApiError",
+    "AtcnClient",
+    "CaptureQueue",
+    "EventSigner",
+    "EvidenceInput",
+    "ReceiptLinkClient",
+    "SubledgerClient",
+    "WEBHOOK_SIGNATURE_HEADER",
+    "acceptance_data",
+    "build_response_statement",
+    "canonicalize",
+    "countersign_payload",
+    "digest_of",
+    "evidence_envelope",
+    "ext",
+    "generate_key_pair",
+    "new_id",
+    "public_key_from_private",
+    "sha256_digest",
+    "sign_payload",
+    "sign_statement",
+    "sign_webhook",
+    "stable_key",
+    "utc_now",
+    "verify_countersignature",
+    "verify_payload",
+    "verify_statement_signature",
+    "verify_webhook",
+]

atcn-1.3.0/src/atcn/__main__.py

@@ -0,0 +1,41 @@
+"""`python -m atcn init [--share-usage yes|no]`: records whether this machine shares anonymous usage metrics."""
+
+import argparse
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from .client import SDK_VERSION
+from .usage import Env, ask_to_share_usage, save_usage_choice, send_usage_report, settings_path, usage_status
+
+
+def main(argv: list[str] | None = None, read_line: Callable[[str], str] = input, write: Callable[[str], Any] = print, interactive: bool | None = None, env: Env | None = None) -> int:
+    """Returns the exit code: 0 saved, 2 usage error or no answer. On a yes, reports integration_initialized."""
+    parser = argparse.ArgumentParser(prog="python -m atcn")
+    parser.add_argument("command", choices=["init"])
+    parser.add_argument("--share-usage", choices=["yes", "no"])
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exit_:
+        return int(exit_.code or 0)
+
+    if args.share_usage is not None:
+        shared: bool | None = save_usage_choice(args.share_usage == "yes", env)["share_usage"]
+    elif interactive if interactive is not None else sys.stdin.isatty():
+        shared = ask_to_share_usage(read_line, write, env)
+    else:
+        write("Not an interactive terminal: pass --share-usage yes or --share-usage no.")
+        return 2
+    if shared is None:
+        write("No answer given; nothing saved.")
+        return 2
+
+    if shared:
+        send_usage_report({"event": "integration_initialized", "sdk_version": f"python/{SDK_VERSION}", "workflow": "custom", "delegations": None, "charges": None}, env)
+    write(f"Saved your choice to {settings_path(env)}.")
+    write(f"Usage metrics: {usage_status(env)['reason']}.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

atcn-1.3.0/src/atcn/canonical.py

@@ -0,0 +1,38 @@
+"""Canonical JSON (RFC 8785 JCS, restricted to safe integers) - byte-identical to the TypeScript SDK."""
+
+import json
+from typing import Any
+
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _utf16_sort_key(key: str) -> bytes:
+    # JCS orders object members by UTF-16 code units, like JavaScript's default sort.
+    return key.encode("utf-16-be")
+
+
+def canonicalize(value: Any) -> str:
+    """Serializes a value canonically. Floats are rejected: amounts are integer minor units."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        if abs(value) > MAX_SAFE_INTEGER:
+            raise ValueError(f"integer {value} exceeds the safe integer range")
+        return str(value)
+    if isinstance(value, float):
+        raise ValueError("floats are not allowed in canonical payloads; use integer minor units")
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonicalize(item) for item in value) + "]"
+    if isinstance(value, dict):
+        for key in value:
+            if not isinstance(key, str):
+                raise ValueError("object keys must be strings")
+        members = sorted(value.items(), key=lambda item: _utf16_sort_key(item[0]))
+        return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + canonicalize(v) for k, v in members) + "}"
+    raise ValueError(f"unsupported type {type(value).__name__}")

atcn-1.3.0/src/atcn/client.py

@@ -0,0 +1,123 @@
+"""Minimal ATCN API client using only the standard library for HTTP."""
+
+import json
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .crypto import Signed
+
+# Must equal the version in pyproject.toml (checked by a test).
+SDK_VERSION = "1.3.0"
+# Names the SDK and its version on every request, so the API operator can count SDK versions in use. Nothing else is sent.
+SDK_HEADER = "atcn-sdk"
+
+
+class AtcnApiError(Exception):
+    def __init__(self, status: int, code: str, message: str, reason: str | None, retryable: bool, correlation_id: str | None):
+        super().__init__(f"{code}{f' ({reason})' if reason else ''}: {message}")
+        self.status = status
+        self.code = code
+        self.reason = reason
+        self.retryable = retryable
+        self.correlation_id = correlation_id
+
+
+class AtcnClient:
+    """Every mutating call carries an Idempotency-Key; signed events use event:<event_id>.
+
+    With share_token, requests authenticate as a receipt-link holder (x-atcn-share-token) instead of with an API key.
+    default_headers are sent on every request.
+    """
+
+    def __init__(self, base_url: str, api_key: str, retries: int = 2, timeout: float = 30.0, share_token: str | None = None, default_headers: dict[str, str] | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.retries = retries
+        self.timeout = timeout
+        self.share_token = share_token
+        self.default_headers = default_headers or {}
+
+    def request(self, method: str, path: str, body: Any = None, idempotency_key: str | None = None, query: dict[str, Any] | None = None, raw: bytes | None = None, headers: dict[str, str] | None = None, content_type: str = "application/octet-stream") -> Any:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode({k: v for k, v in query.items() if v is not None})
+        auth_header = {"x-atcn-share-token": self.share_token} if self.share_token else {"authorization": f"Bearer {self.api_key}"}
+        all_headers = {SDK_HEADER: f"python/{SDK_VERSION}", **auth_header, **self.default_headers, **(headers or {})}
+        data: bytes | None = None
+        if method != "GET":
+            all_headers["idempotency-key"] = idempotency_key or str(uuid.uuid4())
+        if raw is not None:
+            all_headers["content-type"] = content_type
+            data = raw
+        elif body is not None:
+            all_headers["content-type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+
+        attempt = 0
+        while True:
+            attempt += 1
+            request = urllib.request.Request(url, data=data, method=method, headers=all_headers)
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    text = response.read().decode("utf-8")
+                    return json.loads(text) if text and "json" in response.headers.get("content-type", "") else text
+            except urllib.error.HTTPError as http_error:
+                text = http_error.read().decode("utf-8")
+                parsed = json.loads(text) if text.startswith("{") else {}
+                err = parsed.get("error", {})
+                api_error = AtcnApiError(http_error.code, err.get("code", "http_error"), err.get("message", text), err.get("reason"), bool(err.get("retryable")), parsed.get("correlation_id"))
+                if api_error.retryable and attempt <= self.retries:
+                    time.sleep(0.1 * 2**attempt)
+                    continue
+                raise api_error from None
+
+    # Obligations
+    def create_obligation(self, signed: Signed, subledger: dict[str, Any] | None = None) -> Any:
+        """With subledger={"task_id": ..., "parent_delegation_id": ...}, the obligation also becomes a delegation of that task.
+
+        The link is not part of the signed event and is never shared with the counterparty.
+        """
+        body = {**signed, "subledger": subledger} if subledger else signed
+        return self.request("POST", "/v1/obligations", body, f"event:{signed['payload']['event_id']}")
+
+    def accept_obligation(self, obligation_id: str, signed: Signed) -> Any:
+        return self.request("POST", f"/v1/obligations/{obligation_id}/accept", signed, f"event:{signed['payload']['event_id']}")
+
+    def append_event(self, obligation_id: str, signed: Signed) -> Any:
+        return self.request("POST", f"/v1/obligations/{obligation_id}/events", signed, f"event:{signed['payload']['event_id']}")
+
+    def get_obligation(self, obligation_id: str) -> Any:
+        return self.request("GET", f"/v1/obligations/{obligation_id}")
+
+    def list_events(self, obligation_id: str) -> Any:
+        return self.request("GET", f"/v1/obligations/{obligation_id}/events")
+
+    # Evidence and clearing
+    def upload_blob(self, content: bytes, media_type: str = "application/octet-stream") -> Any:
+        return self.request("POST", "/v1/blobs", raw=content, headers={"x-media-type": media_type})
+
+    def submit_evidence(self, obligation_id: str, signed: Signed) -> Any:
+        return self.request("POST", f"/v1/obligations/{obligation_id}/evidence", signed, f"event:{signed['payload']['event_id']}")
+
+    def evaluate(self, obligation_id: str, policy_id: str, policy_version: str, idempotency_key: str | None = None) -> Any:
+        return self.request("POST", f"/v1/obligations/{obligation_id}/evaluate", {"policy_id": policy_id, "policy_version": policy_version}, idempotency_key)
+
+    def finalize(self, decision_id: str, idempotency_key: str | None = None) -> Any:
+        return self.request("POST", f"/v1/decisions/{decision_id}/finalize", None, idempotency_key)
+
+    # Journal, settlement, export
+    def journal(self, **filters: Any) -> Any:
+        return self.request("GET", "/v1/journal", query=filters)
+
+    def report_settlement_event(self, event: dict[str, Any], idempotency_key: str | None = None) -> Any:
+        return self.request("POST", "/v1/settlements/events", event, idempotency_key)
+
+    def export_closure_package(self, obligation_id: str) -> Any:
+        return self.request("GET", f"/v1/exports/{obligation_id}")
+
+    def service_keys(self) -> Any:
+        return self.request("GET", "/v1/service/keys")

atcn-1.3.0/src/atcn/crypto.py

@@ -0,0 +1,78 @@
+"""Ed25519 signing over canonical JSON, SHA-256 digests, and base64url encoding."""
+
+import base64
+import hashlib
+from typing import Any, TypedDict
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+from .canonical import canonicalize
+
+SIGNATURE_ALGORITHM = "Ed25519"
+
+
+class Signature(TypedDict):
+    key_id: str
+    key_version: int
+    algorithm: str
+    value: str
+
+
+class Signed(TypedDict):
+    payload: Any
+    signature: Signature
+
+
+def b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def sha256_digest(data: bytes | str) -> str:
+    raw = data.encode("utf-8") if isinstance(data, str) else data
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def digest_of(value: Any) -> str:
+    """Digest of the canonical JSON form of a value (terms digests, payload hashes)."""
+    return sha256_digest(canonicalize(value))
+
+
+def generate_key_pair() -> tuple[str, str]:
+    """Returns (private_key, public_key) as base64url strings; the private key is the 32-byte seed."""
+    private = Ed25519PrivateKey.generate()
+    seed = private.private_bytes_raw()
+    return b64url_encode(seed), public_key_from_private(b64url_encode(seed))
+
+
+def public_key_from_private(private_key: str) -> str:
+    private = Ed25519PrivateKey.from_private_bytes(b64url_decode(private_key))
+    return b64url_encode(private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw))
+
+
+def sign_bytes(data: bytes, private_key: str) -> str:
+    return b64url_encode(Ed25519PrivateKey.from_private_bytes(b64url_decode(private_key)).sign(data))
+
+
+def verify_bytes(data: bytes, signature: str, public_key: str) -> bool:
+    try:
+        Ed25519PublicKey.from_public_bytes(b64url_decode(public_key)).verify(b64url_decode(signature), data)
+        return True
+    except (InvalidSignature, ValueError):
+        return False
+
+
+def sign_payload(payload: Any, key_id: str, key_version: int, private_key: str) -> Signed:
+    value = sign_bytes(canonicalize(payload).encode("utf-8"), private_key)
+    return {"payload": payload, "signature": {"key_id": key_id, "key_version": key_version, "algorithm": SIGNATURE_ALGORITHM, "value": value}}
+
+
+def verify_payload(signed: Signed, public_key: str) -> bool:
+    if signed["signature"].get("algorithm") != SIGNATURE_ALGORITHM:
+        return False
+    return verify_bytes(canonicalize(signed["payload"]).encode("utf-8"), signed["signature"]["value"], public_key)