sar-envelope 0.1.0__py3-none-any.whl

sar_envelope/__init__.py

@@ -0,0 +1,52 @@
+"""SAR (Settlement Attestation Receipt) portable v0.1 envelope primitives.
+
+Implements exactly four capabilities for the six-field portable signed core
+(`task_id_hash, verdict, confidence, reason_code, ts, verifier_kid`):
+
+1. JCS (RFC 8785) canonicalization — `canonicalize`.
+2. Deterministic receipt/claim ID derivation — `receipt_id`.
+3. Ed25519 signature-input construction — `signing_input`.
+4. Key discovery against a published `.well-known/sar-keys.json` registry —
+   `parse_key_registry`, `resolve_key`, `fetch_key_registry`.
+
+This package does not verify signatures, run a trust registry, or implement
+any issuer-specific extension (e.g. wallet-bound counterparty binding). See
+the README for exact scope.
+"""
+
+from .canonicalize import canonicalize
+from .core import (
+    CORE_FIELDS,
+    CoreFieldError,
+    core_digest,
+    extract_core,
+    receipt_id,
+    signing_input,
+)
+from .keys import (
+    KeyEntry,
+    UnknownKeyError,
+    UnsupportedAlgorithmError,
+    fetch_key_registry,
+    parse_key_registry,
+    resolve_key,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "canonicalize",
+    "CORE_FIELDS",
+    "CoreFieldError",
+    "core_digest",
+    "extract_core",
+    "receipt_id",
+    "signing_input",
+    "KeyEntry",
+    "UnknownKeyError",
+    "UnsupportedAlgorithmError",
+    "fetch_key_registry",
+    "parse_key_registry",
+    "resolve_key",
+    "__version__",
+]

sar_envelope/canonicalize.py

@@ -0,0 +1,20 @@
+"""JCS (RFC 8785) canonicalization.
+
+Thin wrapper around the `jcs` package so callers depend on one stable
+entry point (`canonicalize`) regardless of which conformant JCS library
+backs it.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import jcs as _jcs
+
+
+def canonicalize(value: Any) -> bytes:
+    """Return the RFC 8785 JSON Canonicalization Scheme encoding of `value`.
+
+    `value` must be a JSON-compatible structure (dict/list/str/int/float/
+    bool/None). Returns UTF-8 bytes.
+    """
+    return _jcs.canonicalize(value)

sar_envelope/core.py

@@ -0,0 +1,81 @@
+"""Receipt ID derivation and Ed25519 signature-input construction.
+
+The portable SAR v0.1 signed core is exactly six fields:
+
+    task_id_hash, verdict, confidence, reason_code, ts, verifier_kid
+
+`receipt_id` and `signing_input` are two views of the same underlying
+value: `sha256(JCS(core))`. `receipt_id` hex-encodes it with a `sha256:`
+prefix; `signing_input` returns the raw 32 digest bytes that an Ed25519
+private key signs directly (this profile signs the digest, not the raw
+canonical bytes).
+
+`counterparty` and any `_ext` metadata are never part of this core. That
+is an issuer-specific extension of Default Settlement's wallet-bound
+profile, not the portable v0.1 contract this package implements.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Mapping
+
+from .canonicalize import canonicalize
+
+CORE_FIELDS = (
+    "task_id_hash",
+    "verdict",
+    "confidence",
+    "reason_code",
+    "ts",
+    "verifier_kid",
+)
+
+
+class CoreFieldError(ValueError):
+    """Raised when a receipt/core mapping is missing a required field."""
+
+
+def extract_core(receipt: Mapping[str, Any]) -> dict:
+    """Pull exactly the six signed-core fields out of a full receipt object.
+
+    Raises `CoreFieldError` if any of the six fields is missing. Ignores
+    any other field present on `receipt` (e.g. `receipt_id`, `sig`,
+    `counterparty`, `_ext`) — those are envelope or unsigned metadata,
+    not part of the signed core.
+    """
+    missing = [f for f in CORE_FIELDS if f not in receipt]
+    if missing:
+        raise CoreFieldError(f"receipt is missing required core field(s): {missing}")
+    return {k: receipt[k] for k in CORE_FIELDS}
+
+
+def core_digest(core: Mapping[str, Any]) -> bytes:
+    """Return sha256(JCS(core)) as raw 32 bytes.
+
+    `core` must contain exactly the six `CORE_FIELDS` (extra keys are
+    rejected to avoid silently signing/deriving over the wrong field set —
+    use `extract_core` first if you have a full receipt envelope).
+    """
+    extra = set(core.keys()) - set(CORE_FIELDS)
+    if extra:
+        raise CoreFieldError(f"core contains non-core field(s): {sorted(extra)}")
+    missing = [f for f in CORE_FIELDS if f not in core]
+    if missing:
+        raise CoreFieldError(f"core is missing required field(s): {missing}")
+    canonical = canonicalize(core)
+    return hashlib.sha256(canonical).digest()
+
+
+def receipt_id(core: Mapping[str, Any]) -> str:
+    """Return the deterministic receipt ID: 'sha256:' + hex(core_digest(core))."""
+    return "sha256:" + core_digest(core).hex()
+
+
+def signing_input(core: Mapping[str, Any]) -> bytes:
+    """Return the exact bytes an Ed25519 key signs for this core.
+
+    Under the portable SAR v0.1 profile this is the 32-byte sha256 digest
+    of the JCS-canonicalized core (the same value `receipt_id` hex-encodes),
+    not the raw canonical JSON bytes.
+    """
+    return core_digest(core)

sar_envelope/keys.py

@@ -0,0 +1,99 @@
+"""Key discovery against a published `.well-known/sar-keys.json` registry.
+
+The registry format is a JWK set: `{"keys": [{"kid", "kty", "crv", "x", ...}]}`.
+This module resolves a `kid` to a usable Ed25519 public key and binds the
+algorithm: only `kty == "OKP"` and `crv == "Ed25519"` are recognized. Any
+other `kty`/`crv` combination is treated as an unsupported algorithm, not
+silently accepted.
+
+This module does not implement trust-registry logic (pinning, snapshotting,
+revocation, or refresh policy) — it only parses and resolves. Callers that
+need those properties should build them on top of `parse_key_registry`.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping
+
+
+SUPPORTED_KTY = "OKP"
+SUPPORTED_CRV = "Ed25519"
+
+
+class UnknownKeyError(KeyError):
+    """Raised when a `kid` is not present in the registry."""
+
+
+class UnsupportedAlgorithmError(ValueError):
+    """Raised when a registry entry's kty/crv is not a recognized Ed25519 binding."""
+
+
+@dataclass(frozen=True)
+class KeyEntry:
+    kid: str
+    pubkey: bytes  # raw 32-byte Ed25519 public key
+    alg: str  # always "Ed25519" for entries this module accepts
+    raw: Mapping[str, Any]  # the original JWK entry, for inspection
+
+
+def _b64url_decode(value: str) -> bytes:
+    pad = (4 - (len(value) % 4)) % 4
+    return base64.urlsafe_b64decode(value + ("=" * pad))
+
+
+def parse_key_registry(document: Mapping[str, Any]) -> Dict[str, KeyEntry]:
+    """Parse a `.well-known/sar-keys.json` document into `{kid: KeyEntry}`.
+
+    Only entries with `kty == "OKP"` and `crv == "Ed25519"` are included.
+    Raises `UnsupportedAlgorithmError` if an entry declares a `kid` but an
+    unrecognized kty/crv, since silently skipping it would let a caller
+    believe a key doesn't exist rather than that it exists under an
+    unsupported algorithm binding.
+    """
+    keys = document.get("keys")
+    if not isinstance(keys, list):
+        raise ValueError("registry document must contain a 'keys' list")
+
+    result: Dict[str, KeyEntry] = {}
+    for entry in keys:
+        kid = entry.get("kid")
+        if not kid:
+            continue
+        kty = entry.get("kty")
+        crv = entry.get("crv")
+        if kty != SUPPORTED_KTY or crv != SUPPORTED_CRV:
+            raise UnsupportedAlgorithmError(
+                f"key {kid!r} declares kty={kty!r} crv={crv!r}; only "
+                f"kty={SUPPORTED_KTY!r} crv={SUPPORTED_CRV!r} is supported"
+            )
+        x = entry.get("x")
+        if not x:
+            raise ValueError(f"key {kid!r} is missing required 'x' (public key) field")
+        result[kid] = KeyEntry(kid=kid, pubkey=_b64url_decode(x), alg="Ed25519", raw=entry)
+    return result
+
+
+def resolve_key(registry: Mapping[str, KeyEntry], kid: str) -> KeyEntry:
+    """Resolve `kid` to a `KeyEntry`, raising `UnknownKeyError` if absent."""
+    try:
+        return registry[kid]
+    except KeyError as exc:
+        raise UnknownKeyError(f"unknown key id: {kid!r}") from exc
+
+
+def fetch_key_registry(
+    url: str = "https://defaultverifier.com/.well-known/sar-keys.json",
+    timeout: float = 10.0,
+) -> Dict[str, KeyEntry]:
+    """Fetch and parse a `.well-known/sar-keys.json` registry over HTTPS.
+
+    Convenience wrapper around `parse_key_registry` using only the
+    standard library. Callers who already have the document (e.g. from a
+    pinned snapshot) should call `parse_key_registry` directly instead.
+    """
+    with urllib.request.urlopen(url, timeout=timeout) as response:
+        document = json.load(response)
+    return parse_key_registry(document)

sar_envelope-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: sar-envelope
+Version: 0.1.0
+Summary: Portable SAR (Settlement Attestation Receipt) v0.1 envelope primitives: JCS canonicalization, receipt ID derivation, Ed25519 signature-input construction, and .well-known/sar-keys.json key discovery.
+License: MIT
+Project-URL: Homepage, https://defaultverifier.com
+Project-URL: Fixtures, https://github.com/nutstrut/sar-envelope/tree/main/py/fixtures
+Keywords: sar,jcs,rfc8785,canonicalization,ed25519,receipts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: jcs>=0.2.1
+Requires-Dist: cryptography>=3.4
+
+# sar-envelope (Python)
+
+Envelope primitives for the **portable SAR v0.1 signed core** — the
+six-field `task_id_hash, verdict, confidence, reason_code, ts,
+verifier_kid` contract used across SAR (Settlement Attestation Receipt)
+implementations, including independent implementations on non-EVM/non-
+wallet rails.
+
+This package implements exactly four things:
+
+1. **JCS (RFC 8785) canonicalization** — `canonicalize(value) -> bytes`.
+2. **Deterministic receipt/claim ID derivation** —
+   `receipt_id(core) = "sha256:" + hex(sha256(JCS(core)))`.
+3. **Ed25519 signature-input construction** — `signing_input(core)`
+   returns the exact 32 bytes an Ed25519 key signs (the sha256 digest of
+   the JCS-canonicalized core, not the raw canonical JSON bytes).
+4. **Key discovery** against a published `.well-known/sar-keys.json`
+   registry (JWK format) — `parse_key_registry`, `resolve_key`,
+   `fetch_key_registry`, including `kid` resolution and algorithm binding
+   (only `kty=OKP, crv=Ed25519` is recognized).
+
+It does **not** verify signatures, run a trust registry, implement a CLI,
+or encode any issuer-specific extension (e.g. a wallet-bound counterparty
+binding). `counterparty` and `_ext` are never part of the six-field
+signed core this package computes over.
+
+## Install
+
+```bash
+pip install sar-envelope
+```
+
+## Example
+
+This reproduces fixture `01_valid_portable` from the published conformance
+corpus (see [Fixtures](#fixtures) below) byte-for-byte:
+
+```python
+from sar_envelope import extract_core, receipt_id, signing_input
+
+receipt = {
+    "receipt_version": "0.1",
+    "task_id_hash": "sha256:fixture-portable-task-0001",
+    "verdict": "PASS",
+    "confidence": 1,
+    "reason_code": "SPEC_MATCH",
+    "ts": "2026-07-23T00:00:00Z",
+    "verifier_kid": "fixture-portable-kid-01",
+    "sig_alg": "Ed25519",
+}
+
+core = extract_core(receipt)
+rid = receipt_id(core)
+assert rid == "sha256:be6c760480f4127a842d3321774680531caa4a9acf16684c067086f83a8d8b6f"
+
+# The bytes an Ed25519 private key signs for this receipt:
+digest = signing_input(core)  # 32 bytes; receipt_id hex-encodes this same value
+```
+
+Key discovery against the real published registry format:
+
+```python
+from sar_envelope import fetch_key_registry, resolve_key
+
+registry = fetch_key_registry("https://defaultverifier.com/.well-known/sar-keys.json")
+entry = resolve_key(registry, "sar-prod-ed25519-01")
+entry.pubkey  # raw 32-byte Ed25519 public key
+entry.alg     # "Ed25519" — only OKP/Ed25519 registry entries are returned
+```
+
+## Fixtures
+
+The test suite in this package runs against the canonical Portable SAR
+v0.1 conformance corpus, bundled at `fixtures/portable-sar-fixtures.json`
+and `fixtures/portable-sar-fixture-keys.json`:
+https://github.com/nutstrut/sar-envelope/tree/main/py/fixtures
+
+## Scope and versioning
+
+Implements **SAR v0.1**, portable six-field signed-core profile only.
+Pre-1.0 (`0.1.0`): the API may change before a 1.0 release. This package
+computes canonical bytes, receipt IDs, and signature input deterministically
+from data you supply — it does not itself authenticate a producer's
+identity, prove human authority over an action, or provide any
+end-to-end verification guarantee. Signature verification and trust-registry
+policy (pinning, revocation, refresh) are the caller's responsibility and
+are out of scope for this package.

sar_envelope-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+sar_envelope/__init__.py,sha256=_2gHkh1R4Vm60Ba36UChDhPyejuQy3kX5UErfly75Uc,1388
+sar_envelope/canonicalize.py,sha256=aUi7Vp730NI1tB0X2HX5GKvuWkIuRsi6inphOtuAjRc,546
+sar_envelope/core.py,sha256=iDO9W3kPPMTKytr3P_ehf-1lqj4Aa8VFq8QJJkvp2Sc,2892
+sar_envelope/keys.py,sha256=EbAHYm-6tiGItknLxvsU2WptmlK3ogkVMNIlBA2Qbjs,3648
+sar_envelope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sar_envelope-0.1.0.dist-info/METADATA,sha256=TY7w02bK6Ul6U3LEf7ppojDopGq9nJjJnYb66ilKOCs,4125
+sar_envelope-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sar_envelope-0.1.0.dist-info/top_level.txt,sha256=I-c7AYJRq8qDlcsH71lMLrfqGsxMeAHPm54jCAn1TU0,13
+sar_envelope-0.1.0.dist-info/RECORD,,

sar_envelope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sar_envelope-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sar_envelope