The Principia Machina/TPC-PY/tpc challenge.py

# -*- 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)