Challenge System

After the risk scorer produces a score and the risk level is determined, Attesta selects a challenge — a verification step the human operator must complete before the action proceeds. Challenges scale in difficulty with risk: low-risk actions pass through automatically, while critical actions require multiple independent approvers.

Default Challenge Map

Risk Level	Score Range	Challenge	Min Review Time
LOW	0.0–0.3	Auto-approve (no challenge)	—
MEDIUM	0.3–0.6	ConfirmChallenge	3.0s
HIGH	0.6–0.8	QuizChallenge	10.0s
CRITICAL	0.8–1.0	MultiPartyChallenge	30.0s

The minimum review time prevents “rubber-stamping” — approvals that happen too fast to indicate genuine review. If an operator responds before the minimum time elapses, the challenge is flagged in the audit trail.

The Four Challenge Types

Confirm

Simple Y/N prompt with a mandatory pause. Suitable for state-changing but well-understood actions.

Quiz

Auto-generated comprehension questions from the action context. Forces the operator to read before approving.

Teach-Back

Free-text explanation of what the action will do. Validates understanding through keyword matching and pluggable validators.

Multi-Party

Requires 2+ independent approvers, each completing a different sub-challenge. The strongest verification for irreversible operations.

How Challenge Selection Works

The challenge pipeline follows this sequence:

Gated function called
Risk scorer produces score (0.0–1.0)
Trust engine adjusts effective risk (optional)
RiskLevel.from_score() classifies the level
Challenge map selects the challenge type
Challenge is presented to the operator
Result recorded in audit trail

from attesta import Attesta, RiskLevel
from attesta.challenges import (
    ConfirmChallenge,
    QuizChallenge,
    TeachBackChallenge,
    MultiPartyChallenge,
)

# Default challenge map (built-in)
attesta = Attesta()

# Custom challenge map
attesta = Attesta(
    challenge_map={
        RiskLevel.LOW: None,                     # auto-approve
        RiskLevel.MEDIUM: ConfirmChallenge(),
        RiskLevel.HIGH: QuizChallenge(max_questions=2),
        RiskLevel.CRITICAL: MultiPartyChallenge(required_approvers=3),
    }
)

import { Attesta, RiskLevel } from "@kyberon/attesta";

// Default challenge map (built-in)
const attesta = new Attesta();

// Custom challenge map
const attesta = new Attesta({
  challengeMap: {
    [RiskLevel.LOW]: null,
    [RiskLevel.MEDIUM]: { type: "confirm" },
    [RiskLevel.HIGH]: { type: "quiz", maxQuestions: 2 },
    [RiskLevel.CRITICAL]: { type: "multi_party", requiredApprovers: 3 },
  },
});

Challenge Flow Diagram

Gated function called

The decorated function is intercepted before execution.

Risk scoring (5 factors)

The risk scorer evaluates function name, arguments, hints, domain patterns, and amplifiers to produce a score from 0.0 to 1.0.

Trust adjustment (if enabled)

The trust engine may lower the effective risk for agents with a proven track record.

Challenge selection by risk level

Risk Level	Score Range	Challenge
LOW	below 0.3	Auto-approve
MEDIUM	0.3 — 0.6	Confirm (Y/N)
HIGH	0.6 — 0.8	Quiz (1—3 questions)
CRITICAL	0.8 — 1.0	Multi-party (2+ approvers)

Audit trail (hash chain)

The result — approved, denied, or timed out — is recorded in a tamper-proof, hash-chained audit log.

Minimum Review Times

Every challenge type enforces a minimum review time. If the operator responds faster than this threshold, the approval is still accepted, but it is flagged as a potential “rubber stamp” in the audit trail.

Challenge	Default Min Review	Rationale
Confirm	3.0 seconds	Enough time to read the action summary
Quiz	10.0 seconds	Enough time to read and answer questions
Teach-Back	30.0 seconds	Enough time to compose a meaningful explanation
Multi-Party	Inherited from sub-challenges	Each approver has their own minimum

Customizing Review Times

from attesta.challenges import QuizChallenge

# Require at least 15 seconds of review for quiz challenges
quiz = QuizChallenge(
    max_questions=3,
    min_correct=2,
    min_review_seconds=15.0,
)

import { QuizChallenge } from "@kyberon/attesta";

const quiz = new QuizChallenge({
  maxQuestions: 3,
  minCorrect: 2,
  minReviewSeconds: 15.0,
});

Challenge Outcomes

Every challenge produces one of three outcomes:

Outcome	Effect	Audit Field
Passed	Action is executed	`challenge_passed: true`
Failed	`AttestaDenied` raised, action blocked	`challenge_passed: false`
Timed out	Treated as failure, action blocked	`challenge_passed: false`

When a challenge fails or is denied, the protected function is never executed. Attesta raises an AttestaDenied exception that the calling code must handle.

from attesta import AttestaDenied

try:
    result = delete_user("usr_12345")
except AttestaDenied as e:
    print(f"Action blocked: {e.reason}")
    print(f"Risk score: {e.risk_score}")
    print(f"Challenge type: {e.challenge_type}")

Configuration via YAML

The challenge map and review times can be configured declaratively:

attesta.yaml

policy:
  challenge_map:
    low: auto
    medium: confirm
    high: quiz
    critical: multi_party

  min_review_seconds:
    confirm: 5.0
    quiz: 15.0
    teach_back: 30.0

  multi_party:
    required_approvers: 2

ConfirmChallenge

Simple approval with mandatory pause

QuizChallenge

Auto-generated comprehension questions

Getting Started

Core Concepts

Configuration

Domain Profiles

Examples

Guides

TypeScript

Resources

Challenge System

Default Challenge Map

The Four Challenge Types

Confirm

Quiz

Teach-Back

Multi-Party

How Challenge Selection Works

Challenge Flow Diagram

Minimum Review Times

Customizing Review Times

Challenge Outcomes

Configuration via YAML

ConfirmChallenge

QuizChallenge

​Default Challenge Map

​The Four Challenge Types

Confirm

Quiz

Teach-Back

Multi-Party

​How Challenge Selection Works

​Challenge Flow Diagram

​Minimum Review Times

​Customizing Review Times

​Challenge Outcomes

​Configuration via YAML

ConfirmChallenge

QuizChallenge

Default Challenge Map

The Four Challenge Types

How Challenge Selection Works

Challenge Flow Diagram

Minimum Review Times

Customizing Review Times

Challenge Outcomes

Configuration via YAML