From The Invariance Itself
# -*- coding: utf-8 -*-
"""
TPC-PY --- the execution challenge (D101.1, slot 4d)
====================================================
TPX attests an agent's EXECUTED mode with a fresh challenge at petition and
on every push: it sends a random nonce, the agent returns the challenge
response computed by executed code, and TPX checks it with TPC-PHP. A
right answer is recorded EXECUTED (with the location the agent declared);
a wrong or missing one is recorded REASONED, and every value that push
presents is refused.
WHAT IT ATTESTS. That the agent executes code reproducing TPC's digest.
Not which code, and not that every presented value came from it: TPX's
recomputation of each presented value (TPS 5.3.9) still covers that.
THE FORM
nonce exactly 32 lowercase hexadecimal characters: 128 bits that
TPX draws from a cryptographic random source. The nonce is
untrusted input arriving in an API response, so it is checked
before use; the strict form means it can carry no text.
response digest_fields([CHALLENGE_TAG, CHALLENGE_FORM, nonce]) on the
ratified D97.1 primitive (SHA-256 over the netstring of the
ordered fields; lowercase hex). The tag separates this digest
from every other TPC digest; the form number lets a later
challenge form be told apart.
REFUSED, as ["REFUSED", reason], never raised; the reason never quotes the
input: "nonce is not 32 lowercase hexadecimal characters"
Standard library only; Python 3.8+; Windows/Linux.
"""
import hmac
import re
import tpc_digest as G
TPC_CHALLENGE_VERSION = "0.1.0"
CHALLENGE_TAG = "TPC-EXECUTION-CHALLENGE"
CHALLENGE_FORM = "1"
_NONCE = re.compile(r"[0-9a-f]{32}\Z")
_HEX64 = re.compile(r"[0-9a-f]{64}\Z")
_BAD_NONCE = "nonce is not 32 lowercase hexadecimal characters"
def _nonce_ok(nonce):
return isinstance(nonce, str) and _NONCE.match(nonce) is not None
def challenge_preimage(nonce):
"""The exact bytes hashed, as text (auditable), or ["REFUSED", reason]."""
if not _nonce_ok(nonce):
return ["REFUSED", _BAD_NONCE]
return ["OK", G.preimage_fields([CHALLENGE_TAG, CHALLENGE_FORM, nonce]).decode("ascii")]
def challenge_response(nonce):
"""The agent's side: ["OK", 64-char lowercase hex] or ["REFUSED", reason]."""
if not _nonce_ok(nonce):
return ["REFUSED", _BAD_NONCE]
return ["OK", G.digest_fields([CHALLENGE_TAG, CHALLENGE_FORM, nonce])]
def challenge_verify(nonce, response):
"""TPX's side: True only for a well-formed nonce and the exact lowercase
response. Any malformed input is False, never an exception."""
if not _nonce_ok(nonce):
return False
if not isinstance(response, str) or _HEX64.match(response) is None:
return False
expected = G.digest_fields([CHALLENGE_TAG, CHALLENGE_FORM, nonce])
return hmac.compare_digest(expected, response)
