aimarket-oracle-sortes 0.1.0__tar.gz

aimarket_oracle_sortes-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Package-local, and it exists for two reasons beyond the obvious.
+#
+# 1. It stops hatchling walking up. hatchling picks its build exclusion list by climbing from
+#    here until it finds a .gitignore. With no file at this level it reached
+#    oracles/.gitignore, whose `**/data/` rule is the only thing keeping
+#    data/sortes_signing_key — this oracle's Ed25519 PRIVATE key — out of the sdist. That rule
+#    lives outside the package, so building anywhere the ancestor is unreachable (a CI checkout
+#    of one subdirectory, a Docker build context, an rsync'd release dir) silently removes it.
+#    Reproduced 2026-07-30 on a sibling: an out-of-tree sdist build of oracles/oracles/chronos
+#    packaged its signing key in plaintext. Whoever holds a Sortes secret key can forge its
+#    VRF proofs, which is the entire product.
+#
+# 2. hatchling force-includes whichever exclusion file it found into the sdist, bypassing
+#    `exclude`, so that file WILL be published. Better it be this one than a map of every
+#    secret path in a private monorepo. This is what the publish gate caught here: the
+#    allow-list in pyproject.toml alone was not enough, because the force-include outranks it.
+#
+# The real guarantee is the allow-list in pyproject.toml ([tool.hatch.build.targets.sdist]
+# include) plus the gate in scripts/publish_pypi.sh. This file is the third layer.
+
+data/
+*.egg-info/
+dist/
+build/
+__pycache__/
+.pytest_cache/
+.venv/

aimarket_oracle_sortes-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: aimarket-oracle-sortes
+Version: 0.1.0
+Summary: Sortes — true ECVRF (RFC 9381) verifiable-randomness oracle on oracle-core
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: aimarket-oracle-core>=0.2
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sortes — true ECVRF verifiable-randomness oracle
+
+Sortes draws lots you can verify. It is a **true Verifiable Random Function**
+implementing **ECVRF-EDWARDS25519-SHA512-TAI** exactly per
+[RFC 9381](https://www.rfc-editor.org/rfc/rfc9381) (suite octet `0x03`, over the
+`edwards25519` curve).
+
+For a fixed `(public_key, alpha)` there is **exactly one** valid output `beta`.
+The oracle's secret key selects it deterministically, so — unlike a trusted
+randomness beacon — the oracle **cannot grind or bias the result**, and anyone
+holding the VRF public key can **verify the draw offline** from the 80-byte proof.
+
+## Capabilities
+
+| capability | price | what it does |
+|---|---|---|
+| `sortes.draw@v1` | $0.006 | Draw verifiable randomness for `alpha`. Returns `public_key`, proof (`gamma`, `c`, `s`, `pi`), `beta`, and `output` (uniform `num_bytes`). The secret key is never returned. |
+| `sortes.verify@v1` | $0.001 | Verify `(public_key, alpha, pi)` offline and trustlessly → `{valid, beta}`. |
+
+`alpha` is UTF-8 by default; prefix with `hex:` to pass raw bytes.
+
+## Why it is correct
+
+The implementation is pure Python (`hashlib` + integer math) — the `edwards25519`
+group arithmetic (RFC 8032 §5.1) and the ECVRF construction (RFC 9381 §5) are
+written from scratch, no external crypto libraries. Correctness is proven by the
+**RFC 9381 Appendix B.3 test vectors**: the tests assert that our implementation
+reproduces the published `SK→PK`, the hash-to-curve point `H`, the proof
+commitment `Gamma`, the VRF output `beta`, **and the full 80-byte proof `pi`**
+byte-for-byte for all three vectors. The full-`pi` check pins the little-endian
+`c || s` encoding mandated by RFC 9381 §5.5, so the proofs are byte-interoperable
+with a conformant verifier (e.g. libsodium), not merely self-consistent; the tests
+also confirm the RFC's own published `pi` bytes verify under our verifier. See
+`tests/test_sortes.py`.
+
+## VRF keypair
+
+The oracle holds one VRF keypair. The 32-byte secret key is resolved from
+`SORTES_VRF_SK` (64 hex chars), else a persisted key at `SORTES_VRF_SK_PATH`
+(default `data/sortes_vrf_sk`), else generated once and persisted so the public
+key stays stable across restarts. The secret key never leaves the process; the
+public key is published in every draw and in the manifest description.
+
+## Run
+
+```bash
+# tests (from the monorepo root)
+PYTHONPATH="oracles/core:oracles/oracles/sortes" \
+  platon/backend/.venv/bin/python -m pytest oracles/oracles/sortes/tests/ -q
+
+# serve (port 9310 by default)
+PYTHONPATH="oracles/core:oracles/oracles/sortes" python -m sortes.main
+```
+
+### Environment
+
+| var | default | meaning |
+|---|---|---|
+| `SORTES_PORT` | `9310` | listen port |
+| `SORTES_PUBLIC_URL` | `http://localhost:9310` | advertised base URL |
+| `SORTES_SIGNING_KEY` | `data/sortes_signing_key` | manifest/receipt signing key path |
+| `SORTES_VRF_SK` | _(unset)_ | explicit 32-byte VRF secret key (hex) |
+| `SORTES_VRF_SK_PATH` | `data/sortes_vrf_sk` | persisted VRF secret key path |
+| `SORTES_CORS_ORIGINS` | `*` | allowed CORS origins |

aimarket_oracle_sortes-0.1.0/README.md

@@ -0,0 +1,64 @@
+# Sortes — true ECVRF verifiable-randomness oracle
+
+Sortes draws lots you can verify. It is a **true Verifiable Random Function**
+implementing **ECVRF-EDWARDS25519-SHA512-TAI** exactly per
+[RFC 9381](https://www.rfc-editor.org/rfc/rfc9381) (suite octet `0x03`, over the
+`edwards25519` curve).
+
+For a fixed `(public_key, alpha)` there is **exactly one** valid output `beta`.
+The oracle's secret key selects it deterministically, so — unlike a trusted
+randomness beacon — the oracle **cannot grind or bias the result**, and anyone
+holding the VRF public key can **verify the draw offline** from the 80-byte proof.
+
+## Capabilities
+
+| capability | price | what it does |
+|---|---|---|
+| `sortes.draw@v1` | $0.006 | Draw verifiable randomness for `alpha`. Returns `public_key`, proof (`gamma`, `c`, `s`, `pi`), `beta`, and `output` (uniform `num_bytes`). The secret key is never returned. |
+| `sortes.verify@v1` | $0.001 | Verify `(public_key, alpha, pi)` offline and trustlessly → `{valid, beta}`. |
+
+`alpha` is UTF-8 by default; prefix with `hex:` to pass raw bytes.
+
+## Why it is correct
+
+The implementation is pure Python (`hashlib` + integer math) — the `edwards25519`
+group arithmetic (RFC 8032 §5.1) and the ECVRF construction (RFC 9381 §5) are
+written from scratch, no external crypto libraries. Correctness is proven by the
+**RFC 9381 Appendix B.3 test vectors**: the tests assert that our implementation
+reproduces the published `SK→PK`, the hash-to-curve point `H`, the proof
+commitment `Gamma`, the VRF output `beta`, **and the full 80-byte proof `pi`**
+byte-for-byte for all three vectors. The full-`pi` check pins the little-endian
+`c || s` encoding mandated by RFC 9381 §5.5, so the proofs are byte-interoperable
+with a conformant verifier (e.g. libsodium), not merely self-consistent; the tests
+also confirm the RFC's own published `pi` bytes verify under our verifier. See
+`tests/test_sortes.py`.
+
+## VRF keypair
+
+The oracle holds one VRF keypair. The 32-byte secret key is resolved from
+`SORTES_VRF_SK` (64 hex chars), else a persisted key at `SORTES_VRF_SK_PATH`
+(default `data/sortes_vrf_sk`), else generated once and persisted so the public
+key stays stable across restarts. The secret key never leaves the process; the
+public key is published in every draw and in the manifest description.
+
+## Run
+
+```bash
+# tests (from the monorepo root)
+PYTHONPATH="oracles/core:oracles/oracles/sortes" \
+  platon/backend/.venv/bin/python -m pytest oracles/oracles/sortes/tests/ -q
+
+# serve (port 9310 by default)
+PYTHONPATH="oracles/core:oracles/oracles/sortes" python -m sortes.main
+```
+
+### Environment
+
+| var | default | meaning |
+|---|---|---|
+| `SORTES_PORT` | `9310` | listen port |
+| `SORTES_PUBLIC_URL` | `http://localhost:9310` | advertised base URL |
+| `SORTES_SIGNING_KEY` | `data/sortes_signing_key` | manifest/receipt signing key path |
+| `SORTES_VRF_SK` | _(unset)_ | explicit 32-byte VRF secret key (hex) |
+| `SORTES_VRF_SK_PATH` | `data/sortes_vrf_sk` | persisted VRF secret key path |
+| `SORTES_CORS_ORIGINS` | `*` | allowed CORS origins |

aimarket_oracle_sortes-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+# Renamed from "sortes-oracle" on 2026-07-30, before first publish. Unprefixed short names on
+# PyPI belong to other people and can install colliding top-level modules — the incident
+# that made this a rule is recorded at the top of oracles/core/pyproject.toml. "sortes-oracle"
+# was unclaimed, which is not safe but claimable: anyone taking it makes
+# `pip install sortes-oracle` fetch their code into a namespace this repo imports.
+name = "aimarket-oracle-sortes"
+version = "0.1.0"
+description = "Sortes — true ECVRF (RFC 9381) verifiable-randomness oracle on oracle-core"
+# Both fields are required to publish, not cosmetic: `scripts/publish_pypi.sh` runs
+# `twine check --strict`, which fails a distribution whose `long_description` is empty, so
+# without `readme` the upload aborts after the build. Matches oracles/core.
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = ["aimarket-oracle-core>=0.2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3.0", "pytest-asyncio>=0.24.0", "httpx>=0.27.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sortes"]
+
+# An ALLOW-list, and deliberately not a deny-list — the same reasoning as oracles/core, which
+# is the only place in this family that had one. With no sdist target declared, hatchling falls
+# back to "everything not matched by a discovered .gitignore", and it walks UP for that file.
+# Inside this monorepo it finds oracles/.gitignore, whose `**/data/` rule is the only thing
+# keeping `data/sortes_signing_key` — this oracle's Ed25519 PRIVATE key — out of the tarball.
+# Copy the package anywhere that ancestor is not reachable (a CI checkout of one subdirectory,
+# a Docker build context, an rsync'd release dir) and the rule vanishes with it. That is not
+# hypothetical: an out-of-tree sdist build of oracles/oracles/chronos packaged
+# data/chronos_signing_key in plaintext. A PyPI version can be yanked but never withdrawn, so
+# a key published once is published permanently, and whoever holds it can forge this oracle's
+# proofs — which is the entire trust story of Sortes.
+#
+# An include list cannot be defeated by a missing file.
+[tool.hatch.build.targets.sdist]
+include = [
+    "/sortes",
+    "/tests",
+    "/README.md",
+    "/pyproject.toml",
+]
+# hatchling adds .gitignore to an sdist on its own, regardless of `include`. It is not secret,
+# but it is a map of where the secrets in a private monorepo live. Also caught by the gate in
+# scripts/publish_pypi.sh, which is the point of a gate that does not trust the config.
+exclude = ["/.gitignore"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

aimarket_oracle_sortes-0.1.0/sortes/__init__.py

@@ -0,0 +1 @@
+"""Sortes — a true ECVRF (RFC 9381) verifiable-randomness oracle."""

aimarket_oracle_sortes-0.1.0/sortes/capabilities.py

@@ -0,0 +1,260 @@
+"""Sortes oracle spec — true ECVRF (RFC 9381) draw + offline verify on oracle-core."""
+
+from __future__ import annotations
+
+import os
+import secrets
+from pathlib import Path
+from typing import Any
+
+from oracle_core import Capability, OracleSpec
+
+from sortes import vrf
+
+# Largest output an unbounded caller may request. The protocol layer does NOT
+# validate input against input_schema, so the handler clamps num_bytes itself —
+# otherwise a caller could ask for an arbitrarily large stretched output and pin
+# CPU/memory. 64 is beta's native length; anything above is SHA512-stretched.
+MAX_NUM_BYTES = 64
+# Cap alpha so a single draw cannot be made to hash megabytes (DoS guard).
+MAX_ALPHA_BYTES = 4096
+
+SUITE_STRING = "ECVRF-EDWARDS25519-SHA512-TAI"
+
+
+# --- VRF keypair management ------------------------------------------------
+def _load_or_create_sk() -> bytes:
+    """Resolve the oracle's 32-byte VRF secret key.
+
+    Order of precedence:
+      1) SORTES_VRF_SK env (64 hex chars) — explicit, e.g. for reproducible deploys.
+      2) A persisted key at SORTES_VRF_SK_PATH (default data/sortes_vrf_sk).
+      3) Freshly generated, then persisted so the public key is stable across
+         restarts (an oracle whose PK changes is useless — clients verify against it).
+    The secret key NEVER leaves this module; only the public key is exposed.
+    """
+    env_sk = os.environ.get("SORTES_VRF_SK", "").strip()
+    if env_sk:
+        sk = bytes.fromhex(env_sk)
+        if len(sk) != 32:
+            raise ValueError("SORTES_VRF_SK must be 32 bytes (64 hex chars)")
+        return sk
+
+    path = Path(os.environ.get("SORTES_VRF_SK_PATH", "data/sortes_vrf_sk"))
+    if path.exists():
+        sk = bytes.fromhex(path.read_text().strip())
+        if len(sk) == 32:
+            return sk
+
+    sk = secrets.token_bytes(32)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(sk.hex())
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+    except OSError:
+        # Read-only FS (e.g. ephemeral test env): keep the in-memory key.
+        pass
+    return sk
+
+
+_SK = _load_or_create_sk()
+_PK = vrf.sk_to_pk(_SK)
+PUBLIC_KEY_HEX = _PK.hex()
+
+
+def _alpha_to_bytes(alpha: Any) -> bytes:
+    """Interpret the client seed `alpha`: only a 'hex:'-prefixed string is decoded as raw
+    bytes, everything else is UTF-8 encoded.
+
+    The docstring used to also promise that a "pure-even-length hex string" would be
+    decoded. It never was, and it must not be: a caller seeding with the literal word
+    "deadbeef" means those eight characters, not those four bytes. Guessing by shape makes
+    the wire format ambiguous, which is the one thing a VRF seed cannot afford — the proof
+    binds to exact bytes. The prefix is the disambiguator, and `draw` now emits it."""
+    if alpha is None:
+        raise ValueError("missing 'alpha'")
+    if isinstance(alpha, (bytes, bytearray)):
+        raw = bytes(alpha)
+    else:
+        s = str(alpha)
+        if s.startswith("hex:"):
+            raw = bytes.fromhex(s[4:])
+        else:
+            raw = s.encode("utf-8")
+    if len(raw) > MAX_ALPHA_BYTES:
+        raise ValueError(f"alpha too large (>{MAX_ALPHA_BYTES} bytes)")
+    return raw
+
+
+# --- handlers --------------------------------------------------------------
+def _draw(d: dict[str, Any]) -> dict[str, Any]:
+    alpha_raw = _alpha_to_bytes(d.get("alpha"))
+    num_bytes = max(1, min(int(d.get("num_bytes", 32)), MAX_NUM_BYTES))
+
+    # Dev/test escape hatch: a caller may pass an explicit 32-byte hex `sk` to make
+    # the draw reproducible against published test vectors. Falls back to the
+    # oracle's own persisted key, which is the production path.
+    #
+    # FAIL CLOSED. `sk` is absent from the published input_schema and the protocol
+    # layer does not validate input against that schema (oracle_core hands the raw
+    # dict to the handler), so before this gate any caller could obtain a perfectly
+    # well-formed `sortes.draw` response computed under a key THEY chose, with the
+    # response echoing their own derived `public_key`. Every downstream fairness
+    # claim collapses at that point: a draw certificate that quotes `public_key`
+    # from the response — rather than pinning a key published before the draw —
+    # is forgeable by any entrant. Verified reachable on the live oracle before
+    # this gate existed. Off unless an operator explicitly opts in.
+    sk = _SK
+    pk = _PK
+    dev_sk = d.get("sk")
+    if dev_sk is not None:
+        if os.environ.get("SORTES_ALLOW_CALLER_SK", "0").strip() not in ("1", "true", "TRUE"):
+            raise ValueError(
+                "caller-supplied `sk` is refused: the draw is only meaningful under "
+                "this oracle's own key. Set SORTES_ALLOW_CALLER_SK=1 to reproduce "
+                "published RFC 9381 vectors in a dev or test environment."
+            )
+        sk = bytes.fromhex(str(dev_sk))
+        if len(sk) != 32:
+            raise ValueError("sk must be 32 bytes (64 hex chars)")
+        pk = vrf.sk_to_pk(sk)
+
+    pi = vrf.prove(sk, alpha_raw)
+    gamma = pi[:32]
+    c = pi[32:48]
+    s = pi[48:80]
+    beta = vrf.proof_to_hash(pi)
+    assert beta is not None  # our own proof always decodes
+    output = vrf.expand_output(beta, num_bytes)
+
+    return {
+        "suite": SUITE_STRING,
+        "public_key": pk.hex(),
+        # `hex:`-prefixed, so feeding this response straight back into sortes.verify@v1
+        # works. It used to emit a bare hex string, which _alpha_to_bytes UTF-8 encodes
+        # rather than decodes — so verify hashed the 18 ASCII characters "746573742d…"
+        # instead of the 9 bytes "test-seed" and answered valid:false for every honest
+        # proof the oracle had just issued. The two halves disagreed on the wire format.
+        "alpha": "hex:" + alpha_raw.hex(),
+        "alpha_hex": alpha_raw.hex(),
+        "gamma": gamma.hex(),
+        "c": c.hex(),
+        "s": s.hex(),
+        "pi": pi.hex(),
+        "beta": beta.hex(),
+        "output": output.hex(),
+        "num_bytes": num_bytes,
+    }
+
+
+def _verify(d: dict[str, Any]) -> dict[str, Any]:
+    try:
+        pk = bytes.fromhex(str(d["public_key"]))
+        pi = bytes.fromhex(str(d["pi"]))
+        alpha_raw = _alpha_to_bytes(d.get("alpha"))
+    except (KeyError, ValueError, TypeError) as exc:
+        return {"valid": False, "beta": None, "error": f"malformed input: {exc}"}
+    beta = vrf.verify(pk, alpha_raw, pi)
+    if beta is None:
+        return {"valid": False, "beta": None}
+    return {"valid": True, "beta": beta.hex()}
+
+
+SPEC = OracleSpec(
+    name="Sortes VRF Oracle",
+    product_id="prod-sortes",
+    description=(
+        "Sortes draws lots you can verify. A true ECVRF (RFC 9381, suite "
+        "ECVRF-EDWARDS25519-SHA512-TAI over edwards25519): the output beta is a "
+        "uniform pseudorandom string cryptographically BOUND to the oracle's public "
+        "key and the client's input alpha, and anyone can verify it OFFLINE from the "
+        "80-byte proof. Unlike a trusted beacon the oracle cannot grind the result — "
+        "for a fixed (public_key, alpha) exactly one valid output exists. "
+        f"VRF public key: {PUBLIC_KEY_HEX}."
+    ),
+    public_url=os.environ.get("SORTES_PUBLIC_URL", "http://localhost:9310"),
+    categories=["verifiable-randomness", "vrf", "rfc9381", "sortition", "agent-tooling"],
+    signing_key_path=os.environ.get("SORTES_SIGNING_KEY", "data/sortes_signing_key"),
+    related=["https://github.com/alexar76"],
+    capabilities=[
+        Capability(
+            capability_id="sortes.draw@v1",
+            product_id="prod-sortes",
+            description=(
+                "Draw verifiable randomness for an input alpha. Computes the ECVRF "
+                "proof pi and output beta with the oracle's secret key (never returned), "
+                "binding the result to (public_key, alpha). Returns the public_key, the "
+                "proof components (gamma, c, s, pi), beta, and `output` (num_bytes of "
+                "uniform randomness). Anyone can re-verify offline with sortes.verify@v1."
+            ),
+            handler=_draw,
+            input_schema={
+                "type": "object",
+                "required": ["alpha"],
+                "properties": {
+                    "alpha": {
+                        "type": "string",
+                        "description": "Client seed/message. UTF-8 by default; prefix 'hex:' for raw bytes.",
+                    },
+                    "num_bytes": {
+                        "type": "integer", "minimum": 1, "maximum": MAX_NUM_BYTES, "default": 32,
+                        "description": "Length of the derived uniform `output` (beta is 64 bytes).",
+                    },
+                },
+            },
+            output_schema={
+                "type": "object",
+                "required": ["public_key", "alpha", "pi", "beta", "output", "suite"],
+                "properties": {
+                    "suite": {"type": "string"},
+                    "public_key": {"type": "string"},
+                    "alpha": {"type": "string"},
+                    "gamma": {"type": "string"},
+                    "c": {"type": "string"},
+                    "s": {"type": "string"},
+                    "pi": {"type": "string"},
+                    "beta": {"type": "string"},
+                    "output": {"type": "string"},
+                    "num_bytes": {"type": "integer"},
+                },
+            },
+            price_per_call_usd=0.006,
+            p50_latency_ms=8,
+            success_rate_30d=0.999,
+        ),
+        Capability(
+            capability_id="sortes.verify@v1",
+            product_id="prod-sortes",
+            description=(
+                "Verify an ECVRF proof offline and trustlessly. Given (public_key, "
+                "alpha, pi) returns valid:true with the canonical beta iff the proof is "
+                "the unique correct VRF output for that (public_key, alpha); otherwise "
+                "valid:false. Needs no trust in the oracle."
+            ),
+            handler=_verify,
+            input_schema={
+                "type": "object",
+                "required": ["public_key", "alpha", "pi"],
+                "properties": {
+                    "public_key": {"type": "string", "description": "VRF public key (32-byte hex)."},
+                    "alpha": {"type": "string", "description": "The input that was drawn (UTF-8 or 'hex:' raw)."},
+                    "pi": {"type": "string", "description": "The 80-byte ECVRF proof (hex)."},
+                },
+            },
+            output_schema={
+                "type": "object",
+                "required": ["valid"],
+                "properties": {
+                    "valid": {"type": "boolean"},
+                    "beta": {"type": ["string", "null"]},
+                },
+            },
+            price_per_call_usd=0.001,
+            p50_latency_ms=6,
+            success_rate_30d=0.999,
+        ),
+    ],
+)

aimarket_oracle_sortes-0.1.0/sortes/main.py

@@ -0,0 +1,21 @@
+"""Sortes FastAPI app — the whole AIMarket v2 surface comes from oracle-core."""
+
+from __future__ import annotations
+
+import os
+
+from oracle_core import create_app
+
+from sortes.capabilities import SPEC
+
+app = create_app(SPEC, cors_origins=os.environ.get("SORTES_CORS_ORIGINS", "*"))
+
+
+def main() -> None:
+    import uvicorn
+
+    uvicorn.run("sortes.main:app", host="0.0.0.0", port=int(os.environ.get("SORTES_PORT", "9310")), reload=False)
+
+
+if __name__ == "__main__":
+    main()

aimarket_oracle_sortes-0.1.0/sortes/vrf.py

@@ -0,0 +1,332 @@
+"""ECVRF-EDWARDS25519-SHA512-TAI — a true verifiable random function (RFC 9381).
+
+Sortes draws lots: the output beta is a uniform pseudorandom string bound to a
+public key Y and an input alpha. It is **verifiable offline** by anyone holding Y
+and the 80-byte proof pi — and, crucially, the prover **cannot grind it**. For a
+fixed (Y, alpha) there is exactly ONE valid (pi, beta); the secret key x selects
+it deterministically, so the oracle has no freedom to bias the draw. That is the
+property a trusted randomness beacon cannot offer: a beacon can re-roll until it
+likes the result, a VRF cannot.
+
+This file is pure Python (hashlib, int math) — no numpy, no external crypto. The
+edwards25519 group arithmetic (RFC 8032 §5.1) is implemented from scratch, and the
+ECVRF construction (RFC 9381 §5, suite ECVRF-EDWARDS25519-SHA512-TAI, suite octet
+0x03) is implemented so the RFC 9381 Appendix B.3 test vectors reproduce
+bit-for-bit — including the full 80-byte proof pi, which pins the little-endian
+c||s encoding a conformant verifier checks (see tests/test_sortes.py).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Tuple
+
+# --- field & curve constants (edwards25519, RFC 8032 §5.1) -----------------
+P = 2**255 - 19  # field prime
+# group order of the base point B
+L = 2**252 + 27742317777372353535851937790883648493
+COFACTOR = 8
+# twist constant d = -121665/121666 mod p
+D = (-121665 * pow(121666, P - 2, P)) % P
+# sqrt(-1) mod p, used in point decompression
+SQRT_M1 = pow(2, (P - 1) // 4, P)
+
+SUITE = b"\x03"  # ECVRF-EDWARDS25519-SHA512-TAI suite_string
+PT_LEN = 32  # encoded point length (bytes)
+C_LEN = 16  # challenge length (bytes)
+Q_LEN = 32  # scalar length (bytes)
+
+
+# --- low-level field helpers ----------------------------------------------
+def _inv(z: int) -> int:
+    """Field inverse via Fermat's little theorem (p is prime)."""
+    return pow(z, P - 2, P)
+
+
+def _sha512(*chunks: bytes) -> bytes:
+    h = hashlib.sha512()
+    for c in chunks:
+        h.update(c)
+    return h.digest()
+
+
+# --- extended twisted-Edwards point arithmetic ------------------------------
+# Points are kept in extended homogeneous coordinates (X, Y, Z, T) with
+# x = X/Z, y = Y/Z and T = XY/Z. Addition formulas are the unified ones from
+# RFC 8032 §5.1.4 (Hisil-Wong-Carter-Dawson), valid for all input pairs.
+Point = Tuple[int, int, int, int]
+
+
+def _base_point() -> Point:
+    # B = (x, 4/5) with the standard recovered x (RFC 8032 §5.1).
+    by = (4 * _inv(5)) % P
+    bx = _recover_x(by, 0)
+    return (bx, by, 1, (bx * by) % P)
+
+
+def _recover_x(y: int, sign: int) -> int:
+    """Recover the x-coordinate from y and its sign bit (RFC 8032 §5.1.3)."""
+    if y >= P:
+        return -1  # malformed
+    x2 = ((y * y - 1) * _inv(D * y * y + 1)) % P
+    if x2 == 0:
+        if sign:
+            return -1  # x = 0 cannot have a set sign bit
+        return 0
+    # candidate sqrt
+    x = pow(x2, (P + 3) // 8, P)
+    if (x * x - x2) % P != 0:
+        x = (x * SQRT_M1) % P
+    if (x * x - x2) % P != 0:
+        return -1  # not a square -> not on curve
+    if (x & 1) != sign:
+        x = (P - x) % P
+    return x
+
+
+def point_add(a: Point, b: Point) -> Point:
+    """Unified extended-coordinate addition (RFC 8032 §5.1.4)."""
+    x1, y1, z1, t1 = a
+    x2, y2, z2, t2 = b
+    aa = ((y1 - x1) * (y2 - x2)) % P
+    bb = ((y1 + x1) * (y2 + x2)) % P
+    cc = (t1 * 2 * D * t2) % P
+    dd = (z1 * 2 * z2) % P
+    e = (bb - aa) % P
+    f = (dd - cc) % P
+    g = (dd + cc) % P
+    h = (bb + aa) % P
+    x3 = (e * f) % P
+    y3 = (g * h) % P
+    t3 = (e * h) % P
+    z3 = (f * g) % P
+    return (x3, y3, z3, t3)
+
+
+def scalar_mul(s: int, pt: Point) -> Point:
+    """Constant-shape double-and-add scalar multiplication."""
+    # neutral element (0, 1, 1, 0)
+    result: Point = (0, 1, 1, 0)
+    addend = pt
+    s = s % (L * COFACTOR) if s >= L * COFACTOR else s
+    while s > 0:
+        if s & 1:
+            result = point_add(result, addend)
+        addend = point_add(addend, addend)
+        s >>= 1
+    return result
+
+
+def point_equal(a: Point, b: Point) -> bool:
+    x1, y1, z1, _ = a
+    x2, y2, z2, _ = b
+    if (x1 * z2 - x2 * z1) % P != 0:
+        return False
+    if (y1 * z2 - y2 * z1) % P != 0:
+        return False
+    return True
+
+
+def point_encode(pt: Point) -> bytes:
+    """Compress to 32 bytes (RFC 8032 §5.1.2): y with x's sign in the top bit."""
+    x, y, z, _ = pt
+    zi = _inv(z)
+    x = (x * zi) % P
+    y = (y * zi) % P
+    out = bytearray(y.to_bytes(32, "little"))
+    out[31] |= (x & 1) << 7
+    return bytes(out)
+
+
+def point_decode(data: bytes) -> Point | None:
+    """Decompress a 32-byte point; return None if it is not a valid curve point."""
+    if len(data) != 32:
+        return None
+    b = bytearray(data)
+    sign = (b[31] >> 7) & 1
+    b[31] &= 0x7F
+    y = int.from_bytes(b, "little")
+    if y >= P:
+        return None
+    x = _recover_x(y, sign)
+    if x < 0:
+        return None
+    return (x, y, 1, (x * y) % P)
+
+
+def is_on_curve(pt: Point) -> bool:
+    """-x^2 + y^2 = 1 + d x^2 y^2 (curve equation, affine, via Z)."""
+    x, y, z, t = pt
+    zi = _inv(z)
+    xa = (x * zi) % P
+    ya = (y * zi) % P
+    lhs = (-xa * xa + ya * ya) % P
+    rhs = (1 + D * xa * xa * ya * ya) % P
+    return lhs == rhs
+
+
+# --- scalar / integer string helpers (RFC 9381 §5.5) -----------------------
+# For the edwards25519 ciphersuites RFC 9381 §5.5 fixes int_to_string /
+# string_to_int to the LITTLE-endian convention of RFC 8032 §5.1.2. This must be
+# little-endian: a big-endian implementation is self-consistent (its own verifier
+# still accepts its proofs) and even reproduces Gamma and beta, but it emits the
+# c||s tail of pi byte-reversed, so the 80-byte proof is NOT byte-interoperable
+# with a conformant verifier (libsodium / the CFRG reference). See the full-pi
+# RFC 9381 Appendix B.3 regression test in tests/test_sortes.py.
+def int_to_string(x: int, length: int) -> bytes:
+    """int_to_string — little-endian fixed-length octet string (RFC 9381 §5.5)."""
+    return x.to_bytes(length, "little")
+
+
+def string_to_int(b: bytes) -> int:
+    """string_to_int — little-endian octet string to nonnegative integer (RFC 9381 §5.5)."""
+    return int.from_bytes(b, "little")
+
+
+def _clamp_scalar(h32: bytes) -> int:
+    """RFC 8032 Ed25519 scalar clamping of the first 32 bytes of SHA512(SK)."""
+    a = bytearray(h32)
+    a[0] &= 0xF8
+    a[31] &= 0x7F
+    a[31] |= 0x40
+    return int.from_bytes(a, "little")
+
+
+# --- key expansion (RFC 8032 §5.1.5) ---------------------------------------
+def expand_sk(sk: bytes) -> Tuple[int, bytes, bytes]:
+    """SK (32 bytes) -> (x scalar, truncated_hashed_sk, PK bytes)."""
+    if len(sk) != 32:
+        raise ValueError("secret key must be 32 bytes")
+    h = _sha512(sk)
+    x = _clamp_scalar(h[0:32])
+    truncated = h[32:64]
+    pk = point_encode(scalar_mul(x, _base_point()))
+    return x, truncated, pk
+
+
+def sk_to_pk(sk: bytes) -> bytes:
+    """Derive the 32-byte Ed25519/VRF public key from a 32-byte secret key."""
+    return expand_sk(sk)[2]
+
+
+# --- ECVRF core (RFC 9381 §5.4 / §5.1) -------------------------------------
+def hash_to_curve_tai(pk: bytes, alpha: bytes) -> Point:
+    """ECVRF_hash_to_curve_try_and_increment (§5.4.1.1).
+
+    H = cofactor * (first decodable point of SHA512(suite||0x01||PK||alpha||ctr||0x00)).
+    """
+    for ctr in range(256):
+        h = _sha512(SUITE, b"\x01", pk, alpha, int_to_string(ctr, 1), b"\x00")
+        pt = point_decode(h[0:PT_LEN])
+        if pt is not None:
+            # cofactor clearing: H <- 8 * H
+            return scalar_mul(COFACTOR, pt)
+    raise ValueError("hash_to_curve failed (no point found in 256 tries)")
+
+
+def _challenge_generation(points: list[Point]) -> int:
+    """ECVRF_challenge_generation (§5.4.3): c = int(SHA512(suite||0x02||P1..Pn||0x00)[0:16])."""
+    parts = [SUITE, b"\x02"]
+    for p in points:
+        parts.append(point_encode(p))
+    parts.append(b"\x00")
+    c_string = _sha512(*parts)
+    return string_to_int(c_string[0:C_LEN])
+
+
+def _nonce_generation(truncated_hashed_sk: bytes, h_point: Point) -> int:
+    """ECVRF_nonce_generation_RFC8032 (§5.4.2.2)."""
+    k_string = _sha512(truncated_hashed_sk, point_encode(h_point))
+    return string_to_int(k_string) % L
+
+
+def _gamma_to_hash(gamma: Point) -> bytes:
+    """ECVRF_proof_to_hash beta = SHA512(suite||0x03||encode(cofactor*Gamma)||0x00)."""
+    cofactor_gamma = scalar_mul(COFACTOR, gamma)
+    return _sha512(SUITE, b"\x03", point_encode(cofactor_gamma), b"\x00")
+
+
+def prove(sk: bytes, alpha: bytes) -> bytes:
+    """ECVRF_prove (§5.1): return the 80-byte proof pi for (SK, alpha)."""
+    x, truncated_hashed_sk, pk = expand_sk(sk)
+    base = _base_point()
+    h = hash_to_curve_tai(pk, alpha)
+    gamma = scalar_mul(x, h)
+    k = _nonce_generation(truncated_hashed_sk, h)
+    u = scalar_mul(k, base)  # k*B
+    v = scalar_mul(k, h)  # k*H
+    y = scalar_mul(x, base)  # public-key point Y = x*B
+    # RFC 9381 §5.1 step 6: c = challenge_generation(Y, H, Gamma, k*B, k*H).
+    # The public key Y MUST be the first transcript point — omitting it yields
+    # proofs a conformant RFC-9381 verifier would reject (output beta is the same,
+    # but interop breaks), which would defeat the whole point of a standard VRF.
+    c = _challenge_generation([y, h, gamma, u, v])
+    s = (k + c * x) % L
+    return point_encode(gamma) + int_to_string(c, C_LEN) + int_to_string(s, Q_LEN)
+
+
+def proof_to_hash(pi: bytes) -> bytes | None:
+    """ECVRF_proof_to_hash (§5.2): decode pi and return the 64-byte beta (or None)."""
+    decoded = decode_proof(pi)
+    if decoded is None:
+        return None
+    gamma, _c, _s = decoded
+    return _gamma_to_hash(gamma)
+
+
+def decode_proof(pi: bytes) -> Tuple[Point, int, int] | None:
+    """ECVRF_decode_proof (§5.4.4): pi (80 bytes) -> (Gamma, c, s) or None if malformed."""
+    if len(pi) != PT_LEN + C_LEN + Q_LEN:
+        return None
+    gamma = point_decode(pi[0:PT_LEN])
+    if gamma is None:
+        return None
+    c = string_to_int(pi[PT_LEN:PT_LEN + C_LEN])
+    s = string_to_int(pi[PT_LEN + C_LEN:PT_LEN + C_LEN + Q_LEN])
+    if s >= L:  # scalar must be reduced (non-malleable)
+        return None
+    return gamma, c, s
+
+
+def verify(pk: bytes, alpha: bytes, pi: bytes) -> bytes | None:
+    """ECVRF_verify (§5.3): return beta (64 bytes) iff pi is valid for (PK, alpha), else None."""
+    y = point_decode(pk)
+    if y is None:
+        return None
+    decoded = decode_proof(pi)
+    if decoded is None:
+        return None
+    gamma, c, s = decoded
+    base = _base_point()
+    h = hash_to_curve_tai(pk, alpha)
+    # U = s*B - c*Y ; V = s*H - c*Gamma
+    u = point_add(scalar_mul(s, base), _negate(scalar_mul(c, y)))
+    v = point_add(scalar_mul(s, h), _negate(scalar_mul(c, gamma)))
+    # RFC 9381 §5.3 step 10: c' = challenge_generation(Y, H, Gamma, U, V).
+    c_prime = _challenge_generation([y, h, gamma, u, v])
+    if c_prime != c:
+        return None
+    return _gamma_to_hash(gamma)
+
+
+def _negate(pt: Point) -> Point:
+    x, y, z, t = pt
+    return ((-x) % P, y, z, (-t) % P)
+
+
+# --- output stretching ------------------------------------------------------
+def expand_output(beta: bytes, num_bytes: int) -> bytes:
+    """Derive `num_bytes` of uniform output from the 64-byte beta.
+
+    For num_bytes <= 64 this is a prefix of beta; for larger requests beta is
+    used as a key in a SHA512 counter-mode stream so the result stays uniform
+    and fully determined by beta (hence still verifiable & ungrindable).
+    """
+    if num_bytes <= len(beta):
+        return beta[:num_bytes]
+    out = bytearray()
+    ctr = 0
+    while len(out) < num_bytes:
+        out += _sha512(beta, int_to_string(ctr, 4))
+        ctr += 1
+    return bytes(out[:num_bytes])

aimarket_oracle_sortes-0.1.0/tests/test_sortes.py

@@ -0,0 +1,314 @@
+"""Sortes tests — the RFC 9381 ECVRF-EDWARDS25519-SHA512-TAI test vectors are the
+decisive correctness proof. If our edwards25519 + ECVRF implementation reproduces
+the published (SK->PK) and (SK,alpha)->pi->beta bytes exactly, it is correct."""
+
+import json
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from sortes import vrf
+from sortes.capabilities import PUBLIC_KEY_HEX
+from sortes.main import app
+
+# --- RFC 9381 Appendix B.3: ECVRF-EDWARDS25519-SHA512-TAI test vectors ------
+# (suite_string = 0x03). Each tuple: (SK, PK, alpha_bytes, H, gamma, beta).
+#
+# These are the values published in RFC 9381 Appendix B.3. The decisive anchors
+# are SK->PK, the hash_to_curve point H, the proof's binding commitment Gamma
+# (== the first 32 bytes of the published pi), and beta (the VRF *output*, which
+# is SHA512(0x03||0x03||encode(8*Gamma)||0x00) — i.e. fully determined by Gamma).
+# If an implementation reproduces PK, H, Gamma AND beta for all three vectors and
+# its own proofs verify, it is a correct ECVRF-EDWARDS25519-SHA512-TAI per RFC 9381:
+# a wrong scalar/challenge could not yield the correct Gamma together with a
+# self-consistent verify. We also pin the full 80-byte pi we emit as a regression
+# anchor (the c||s tail is exercised end-to-end by the verify roundtrip below).
+RFC9381_TAI_VECTORS = [
+    (
+        "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60",
+        "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a",
+        b"",  # empty alpha
+        "91bbed02a99461df1ad4c6564a5f5d829d0b90cfc7903e7a5797bd658abf3318",  # H
+        "8657106690b5526245a92b003bb079ccd1a92130477671f6fc01ad16f26f723f",  # Gamma
+        "90cf1df3b703cce59e2a35b925d411164068269d7b2d29f3301c03dd757876ff"
+        "66b71dda49d2de59d03450451af026798e8f81cd2e333de5cdf4f3e140fdd8ae",  # beta
+    ),
+    (
+        "4ccd089b28ff96da9db6c346ec114e0f5b8a319f35aba624da8cf6ed4fb8a6fb",
+        "3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c",
+        bytes([0x72]),  # alpha = 0x72
+        "5b659fc3d4e9263fd9a4ed1d022d75eaacc20df5e09f9ea937502396598dc551",  # H
+        "f3141cd382dc42909d19ec5110469e4feae18300e94f304590abdced48aed593",  # Gamma
+        "eb4440665d3891d668e7e0fcaf587f1b4bd7fbfe99d0eb2211ccec90496310eb"
+        "5e33821bc613efb94db5e5b54c70a848a0bef4553a41befc57663b56373a5031",  # beta
+    ),
+    (
+        "c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7",
+        "fc51cd8e6218a1a38da47ed00230f0580816ed13ba3303ac5deb911548908025",
+        bytes([0xAF, 0x82]),  # alpha = 0xaf82
+        "bf4339376f5542811de615e3313d2b36f6f53c0acfebb482159711201192576a",  # H
+        "9bc0f79119cc5604bf02d23b4caede71393cedfbb191434dd016d30177ccbf80",  # Gamma
+        "645427e5d00c62a23fb703732fa5d892940935942101e456ecca7bb217c61c45"
+        "2118fec1219202a0edcf038bb6373241578be7217ba85a2687f7a0310b2df19f",  # beta
+    ),
+]
+
+
+# Full 80-byte proofs pi from the SAME RFC 9381 Appendix B.3 examples (16, 17, 18).
+# Unlike H/Gamma/beta (which are independent of the c||s encoding), pi pins the
+# challenge c and scalar s — the exact bytes a *conformant* ECVRF verifier
+# (e.g. libsodium / the CFRG reference) checks. These match ONLY when
+# int_to_string/string_to_int use the RFC-mandated little-endian convention
+# (RFC 9381 §5.5). A big-endian implementation stays self-consistent and still
+# reproduces Gamma and beta, but emits a byte-reversed c||s tail, so this test
+# FAILS for it — that is the byte-interoperability regression guard.
+RFC9381_TAI_PI = [
+    ("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60", b"",
+     "8657106690b5526245a92b003bb079ccd1a92130477671f6fc01ad16f26f723f"
+     "26f8a57ccaed74ee1b190bed1f479d9727d2d0f9b005a6e456a35d4fb0daab126"
+     "8a1b0db10836d9826a528ca76567805"),
+    ("4ccd089b28ff96da9db6c346ec114e0f5b8a319f35aba624da8cf6ed4fb8a6fb", bytes([0x72]),
+     "f3141cd382dc42909d19ec5110469e4feae18300e94f304590abdced48aed593"
+     "3bf0864a62558b3ed7f2fea45c92a465301b3bbf5e3e54ddf2d935be3b67926d"
+     "a3ef39226bbc355bdc9850112c8f4b02"),
+    ("c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7", bytes([0xAF, 0x82]),
+     "9bc0f79119cc5604bf02d23b4caede71393cedfbb191434dd016d30177ccbf80"
+     "96bb474e53895c362d8628ee9f9ea3c0e52c7a5c691b6c18c9979866568add7a"
+     "2d41b00b05081ed0f58ee5e31b3a970e"),
+]
+
+
+class TestRFC9381FullProof:
+    """Byte-interoperability: the full 80-byte pi must match RFC 9381 Appendix B.3."""
+
+    @pytest.mark.parametrize("sk,alpha,pi", RFC9381_TAI_PI)
+    def test_prove_full_pi_matches_rfc(self, sk, alpha, pi):
+        # The decisive byte-conformance check. Fails under a big-endian c||s
+        # encoding even though Gamma/beta still match; passes only for the
+        # RFC-mandated little-endian encoding (RFC 9381 §5.5).
+        assert vrf.prove(bytes.fromhex(sk), alpha).hex() == pi
+
+    @pytest.mark.parametrize("sk,alpha,pi", RFC9381_TAI_PI)
+    def test_rfc_reference_pi_verifies(self, sk, alpha, pi):
+        # The proof bytes as published by the RFC must verify under our verifier
+        # (i.e. our verifier is conformant, not merely self-consistent).
+        pk = vrf.sk_to_pk(bytes.fromhex(sk))
+        assert vrf.verify(pk, alpha, bytes.fromhex(pi)) is not None
+
+
+class TestRFC9381Vectors:
+    @pytest.mark.parametrize("sk,pk,alpha,h,gamma,beta", RFC9381_TAI_VECTORS)
+    def test_sk_to_pk(self, sk, pk, alpha, h, gamma, beta):
+        assert vrf.sk_to_pk(bytes.fromhex(sk)).hex() == pk
+
+    @pytest.mark.parametrize("sk,pk,alpha,h,gamma,beta", RFC9381_TAI_VECTORS)
+    def test_hash_to_curve_matches_H(self, sk, pk, alpha, h, gamma, beta):
+        H = vrf.hash_to_curve_tai(bytes.fromhex(pk), alpha)
+        assert vrf.point_encode(H).hex() == h
+
+    @pytest.mark.parametrize("sk,pk,alpha,h,gamma,beta", RFC9381_TAI_VECTORS)
+    def test_prove_gamma_matches(self, sk, pk, alpha, h, gamma, beta):
+        # Gamma is the first 32 bytes of pi and binds the output to (PK, alpha).
+        pi = vrf.prove(bytes.fromhex(sk), alpha)
+        assert pi[:32].hex() == gamma
+
+    @pytest.mark.parametrize("sk,pk,alpha,h,gamma,beta", RFC9381_TAI_VECTORS)
+    def test_prove_beta_matches(self, sk, pk, alpha, h, gamma, beta):
+        # beta is the actual VRF output (SHA512 over 8*Gamma) — the decisive bytes.
+        pi = vrf.prove(bytes.fromhex(sk), alpha)
+        assert vrf.proof_to_hash(pi).hex() == beta
+
+    @pytest.mark.parametrize("sk,pk,alpha,h,gamma,beta", RFC9381_TAI_VECTORS)
+    def test_own_proof_verifies_to_beta(self, sk, pk, alpha, h, gamma, beta):
+        pi = vrf.prove(bytes.fromhex(sk), alpha)
+        out = vrf.verify(bytes.fromhex(pk), alpha, pi)
+        assert out is not None and out.hex() == beta
+
+
+class TestVRFRoundtrip:
+    SK = bytes.fromhex("c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7")
+
+    def test_draw_verify_roundtrip(self):
+        pk = vrf.sk_to_pk(self.SK)
+        alpha = b"draw-for-agent-42"
+        pi = vrf.prove(self.SK, alpha)
+        beta = vrf.verify(pk, alpha, pi)
+        assert beta is not None
+        assert beta == vrf.proof_to_hash(pi)
+
+    def test_tampered_pi_rejected(self):
+        pk = vrf.sk_to_pk(self.SK)
+        alpha = b"lottery-round-7"
+        pi = bytearray(vrf.prove(self.SK, alpha))
+        pi[40] ^= 0x01  # flip a bit inside c
+        assert vrf.verify(pk, alpha, bytes(pi)) is None
+
+    def test_wrong_alpha_rejected(self):
+        pk = vrf.sk_to_pk(self.SK)
+        pi = vrf.prove(self.SK, b"alpha-A")
+        assert vrf.verify(pk, b"alpha-B", pi) is None
+
+    def test_wrong_pk_rejected(self):
+        other_pk = vrf.sk_to_pk(bytes.fromhex("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60"))
+        alpha = b"bound-to-the-key"
+        pi = vrf.prove(self.SK, alpha)
+        assert vrf.verify(other_pk, alpha, pi) is None
+
+    def test_scalar_s_out_of_range_rejected(self):
+        # s >= L must be rejected by decode_proof (non-malleability).
+        pk = vrf.sk_to_pk(self.SK)
+        alpha = b"x"
+        pi = bytearray(vrf.prove(self.SK, alpha))
+        # s is little-endian per RFC 9381 §5.5; encode L+1 the same way so this
+        # genuinely sets an out-of-range scalar that decode_proof must reject.
+        pi[48:80] = (vrf.L + 1).to_bytes(32, "little")
+        assert vrf.verify(pk, alpha, bytes(pi)) is None
+
+    def test_ungrindable_determinism(self):
+        # The VRF is a function: same (SK, alpha) -> identical pi & beta every time.
+        a = vrf.prove(self.SK, b"same-input")
+        b = vrf.prove(self.SK, b"same-input")
+        assert a == b
+        assert vrf.prove(self.SK, b"other-input") != a
+
+    def test_output_stretch_is_deterministic(self):
+        beta = bytes(range(64))
+        # up to 64 bytes: a prefix of beta
+        assert vrf.expand_output(beta, 16) == beta[:16]
+        assert vrf.expand_output(beta, 64) == beta
+        # beyond 64: a deterministic SHA512 counter stream keyed on beta
+        long1 = vrf.expand_output(beta, 100)
+        long2 = vrf.expand_output(beta, 100)
+        assert len(long1) == 100 and long1 == long2
+        # different beta -> different stretch (ungrindable, still bound to beta)
+        assert vrf.expand_output(bytes(range(1, 65)), 100) != long1
+
+
+class TestPointArithmetic:
+    def test_base_point_on_curve(self):
+        assert vrf.is_on_curve(vrf._base_point())
+
+    def test_encode_decode_roundtrip(self):
+        pk = vrf.sk_to_pk(bytes.fromhex("4ccd089b28ff96da9db6c346ec114e0f5b8a319f35aba624da8cf6ed4fb8a6fb"))
+        pt = vrf.point_decode(pk)
+        assert pt is not None and vrf.is_on_curve(pt)
+        assert vrf.point_encode(pt) == pk
+
+    def test_scalar_mul_order(self):
+        # L * B == identity
+        ident = vrf.scalar_mul(vrf.L, vrf._base_point())
+        assert vrf.point_equal(ident, (0, 1, 1, 0))
+
+
+class TestSortesApp:
+    @pytest.mark.asyncio
+    async def test_draw_then_verify_via_invoke(self):
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://t") as c:
+            dr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.draw@v1",
+                "input": {"alpha": "agent-seed-1", "num_bytes": 32},
+            })).json()
+            assert dr["ok"] is True
+            out = dr["output"]
+            assert out["suite"] == "ECVRF-EDWARDS25519-SHA512-TAI"
+            assert out["public_key"] == PUBLIC_KEY_HEX
+            assert len(out["pi"]) == 160  # 80 bytes hex
+            assert len(out["output"]) == 64  # 32 bytes hex
+            assert "sk" not in out  # the secret key is NEVER returned
+
+            vr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.verify@v1",
+                "input": {"public_key": out["public_key"], "alpha": "agent-seed-1", "pi": out["pi"]},
+            })).json()
+            assert vr["ok"] is True
+            assert vr["output"]["valid"] is True
+            assert vr["output"]["beta"] == out["beta"]
+
+    @pytest.mark.asyncio
+    async def test_verify_rejects_tampered_via_invoke(self):
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://t") as c:
+            dr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.draw@v1", "input": {"alpha": "x"},
+            })).json()
+            out = dr["output"]
+            bad = "00" + out["pi"][2:]  # corrupt first byte
+            vr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.verify@v1",
+                "input": {"public_key": out["public_key"], "alpha": "x", "pi": bad},
+            })).json()
+            assert vr["ok"] is True
+            assert vr["output"]["valid"] is False
+            assert vr["output"]["beta"] is None
+
+    @pytest.mark.asyncio
+    async def test_caller_supplied_sk_is_refused_by_default(self, monkeypatch):
+        """A draw under a key the CALLER chose is worthless, so it must be refused.
+
+        `sk` is not in the published input_schema and oracle_core does not validate
+        input against the schema, so this handler is the only gate. Without it any
+        caller gets a well-formed draw response echoing their own `public_key` —
+        which makes any certificate that trusts the response's `public_key`
+        forgeable by an entrant. Default-off, opt-in for RFC-vector reproduction.
+        """
+        monkeypatch.delenv("SORTES_ALLOW_CALLER_SK", raising=False)
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://t") as c:
+            dr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.draw@v1",
+                "input": {
+                    "alpha": "winner-draw-2026",
+                    "sk": "01" * 32,
+                },
+            })).json()
+        # The attacker's key must never appear, and the oracle must not have drawn.
+        body = json.dumps(dr)
+        assert vrf.sk_to_pk(bytes.fromhex("01" * 32)).hex() not in body
+        assert dr.get("ok") is not True
+
+    @pytest.mark.asyncio
+    async def test_draw_with_dev_sk_reproduces_rfc_vector(self, monkeypatch):
+        # The dev `sk` passthrough lets a caller reproduce a published RFC vector.
+        # We pin the public key, the binding commitment gamma, and the VRF output
+        # beta — all RFC 9381 Appendix B.3 (Example 18) values.
+        monkeypatch.setenv("SORTES_ALLOW_CALLER_SK", "1")
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://t") as c:
+            dr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.draw@v1",
+                "input": {"alpha": "hex:af82",
+                          "sk": "c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7"},
+            })).json()
+            out = dr["output"]
+            assert out["public_key"] == "fc51cd8e6218a1a38da47ed00230f0580816ed13ba3303ac5deb911548908025"
+            assert out["gamma"] == "9bc0f79119cc5604bf02d23b4caede71393cedfbb191434dd016d30177ccbf80"
+            assert out["beta"] == (
+                "645427e5d00c62a23fb703732fa5d892940935942101e456ecca7bb217c61c45"
+                "2118fec1219202a0edcf038bb6373241578be7217ba85a2687f7a0310b2df19f"
+            )
+            # the proof the oracle emits must verify offline (full pi exercised here)
+            vr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.verify@v1",
+                "input": {"public_key": out["public_key"], "alpha": "hex:af82", "pi": out["pi"]},
+            })).json()
+            assert vr["output"]["valid"] is True and vr["output"]["beta"] == out["beta"]
+
+    @pytest.mark.asyncio
+    async def test_missing_alpha_errors(self):
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://t") as c:
+            dr = (await c.post("/ai-market/v2/invoke", json={
+                "capability_id": "sortes.draw@v1", "input": {},
+            })).json()
+            assert dr["ok"] is False
+            assert "alpha" in dr["error"]
+
+    @pytest.mark.asyncio
+    async def test_manifest_signed(self):
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://t") as c:
+            m = (await c.get("/ai-market/v2/manifest")).json()
+        ids = {t["capability_id"] for t in m["tools"]}
+        assert ids == {"sortes.draw@v1", "sortes.verify@v1"}
+        assert app.state.protocol.signer.verify_manifest_signature(m) is True

aimarket_oracle_sortes-0.1.0/tests/test_vrf.py

@@ -0,0 +1,38 @@
+
+
+# ── draw → verify must round-trip ────────────────────────────────
+# `draw` emitted `alpha` as a bare hex string; `_alpha_to_bytes` only decodes hex behind a
+# `hex:` prefix, so verify UTF-8 encoded those hex characters and hashed 18 bytes where the
+# prover had hashed 9. Every honest proof the oracle issued verified as false — a paid
+# verification capability that could not confirm its own output.
+
+from sortes import capabilities as C
+
+
+def test_draw_output_verifies_as_issued():
+    d = C._draw({"alpha": "test-seed"})
+    out = C._verify({"public_key": d["public_key"], "alpha": d["alpha"], "pi": d["pi"]})
+    assert out["valid"] is True, "the oracle cannot verify a proof it just produced"
+    assert out["beta"] == d["beta"]
+
+
+def test_the_original_seed_also_verifies():
+    """A caller who kept their own seed string, rather than the echoed alpha, must not be
+    told their valid proof is invalid either."""
+    d = C._draw({"alpha": "test-seed"})
+    assert C._verify({"public_key": d["public_key"], "alpha": "test-seed", "pi": d["pi"]})["valid"]
+
+
+def test_a_hex_looking_seed_stays_text():
+    """Decoding by shape would make the wire format ambiguous: 'deadbeef' as a seed means
+    eight characters, and the proof binds to exact bytes."""
+    assert C._alpha_to_bytes("deadbeef") == b"deadbeef"
+    assert C._alpha_to_bytes("hex:deadbeef") == bytes.fromhex("deadbeef")
+
+
+def test_forgeries_still_fail():
+    d = C._draw({"alpha": "test-seed"})
+    pk, pi = d["public_key"], d["pi"]
+    assert not C._verify({"public_key": pk, "alpha": "hex:00", "pi": pi})["valid"]
+    assert not C._verify({"public_key": pk, "alpha": d["alpha"], "pi": "00" * 40})["valid"]
+    assert not C._verify({"public_key": "00" * 32, "alpha": d["alpha"], "pi": pi})["valid"]