Zain Dana HarperProof Surface · authorization checks

Check an agent action before it runs.

Proof Surface is a Python library and telos-proof CLI that validates records of AI workflow steps, authorizations, delegations and finished work, and returns allow, deny or needs-human recommendations. It never runs the action itself.

See it work, step by step: an animated walkthrough with the real commands and output from the repository.

0.1.0 on PyPI · source 0.2.0 · Python standard library only

Source

The source on GitHub is version 0.2.0. Version 0.1.0 is on PyPI as proof-surface. The full test set runs with pytest.

What it checks

You pass Proof Surface a planned action, the permission behind it, a budget and, if you have one, an observation of the current state. It returns allow, deny or needs-human, with the reason for each part. Your program does the enforcing.

authorization receipta grant from a person, with an expiry and an explicit list of allowed actions; an empty list allows nothing
pre-execution checkreturns a GateDecision; anything it cannot confirm becomes needs-human
delegation chainpermission handed from a person to agents; each hop can only narrow it, and the first hop must be a person
work-record receipta record of what an agent did, for review
evaluation contractdeploy, block or needs-human against thresholds you set; a result too close to call goes to a person
claim ledgerclaims shared between agents, with confidence and links to what each depends on or conflicts with

Evidence packets for eleven domains

Version 0.2.0 adds one command that turns output a tool already produces into a validated packet with a MATCH, DRIFT or UNVERIFIABLE verdict:

$ telos-proof <domain> --input run.json --claim "..." --scope "..." --out ./artifacts

Domains: agent-action, visual-measurement, research-claim, model-eval, optimization-workflow, rollout-receipt, eval-attempt, ai4science, conservation, control-certificate and competition-attempt.

The trace_adapters layer reads traces and runs from tools you may already use: OpenTelemetry, LangSmith, Langfuse, MLflow, Weights & Biases, Braintrust, Arize Phoenix, promptfoo, Helicone, DVC and SLSA / in-toto. Each importer lists the fields its export cannot supply.

A receipt bundle can carry records from Crucible, Forum, Index, Gather, Learn and EMET together, and Proof Surface validates it without any of those tools installed.

Examples

Exhibit I missing or empty permission
# a gate request (dict) whose authorization receipt is absent
>>> evaluate_gate(request)
GateDecision(decision="deny")
  authorization: no receipt, deny
  budget:        unknown, needs-human
  state:         no observation, needs-human

# an authorization receipt whose allowed_actions list is empty
>>> check_action(receipt, "write_file")
False   # empty allowlist authorizes nothing

# a receipt dict missing expires_at: validation rejects it
>>> validate_authorization_receipt({"allowed_actions": ["write_file"]})
invalid: "expires_at" required, authority must expire

$ pytest
652 passed in 1.89s

Code: proof_surface/pre_execution_gate.py and proof_surface/authorization_receipt.py in github.com/HarperZ9/proof-surface.

Exhibit II a delegation that widens its scope
# root hop: human grants agent-A a scope of ["read_log"]
# second hop: agent-A tries to delegate ["read_log", "write_config"], wider
>>> verify_delegation(chain)
DENIED   # hop 1 scope is not a subset of hop 0: privilege escalation

# a chain whose root from-field is an agent, not a human
>>> verify_delegation(chain_rooted_in_agent)
DENIED   # root hop must be a human: authority cannot originate with an agent

# a valid chain: human → agent-A ["read_log"] → agent-B ["read_log"]
>>> verify_delegation(valid_chain)
VALID    effective_scope = ["read_log"]

Code: proof_surface/delegation_chain.py. The hash chain detects a damaged, removed or added hop. To detect a chain that was rewritten and sealed again, keep a copy of chain_binding elsewhere or check a signature.

Sample reports

Review packets from an early run, in an earlier format: a release-readiness report, an EMET sample, a proof-index, and a public-surface-sweeper review.

GitHub: HarperZ9/proof-surface  ·  Email: zaindharper@gmail.com  ·  ← the map  ·  the index