Architecture

TapPass sits between your AI agents and LLM providers. Every request passes through a governance pipeline before reaching the LLM, and every response is scanned before reaching the agent.

System architecture

graph LR
    subgraph Agents
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent N]
    end

    subgraph TapPass Gateway
        GW[Gateway]
        PP[Pipeline<br/>49 steps]
        PA[Policy Engine<br/>OPA]
        AU[Audit Trail<br/>Hash chain]
        ID[Identity<br/>RBAC + SPIFFE]
        VT[Vault<br/>Credentials]
    end

    subgraph LLM Providers
        OAI[OpenAI]
        ANT[Anthropic]
        AZ[Azure OpenAI]
        GEM[Google Gemini]
    end

    A1 -->|tp_ key| GW
    A2 -->|tp_ key| GW
    A3 -->|tp_ key| GW
    GW --> PP
    PP <--> PA
    PP --> AU
    GW <--> ID
    GW --> VT
    VT -->|sk_ key| OAI
    VT -->|sk-ant_ key| ANT
    VT -->|Azure key| AZ
    VT -->|Google key| GEM

The proxy pattern

TapPass acts as a transparent proxy between your agents and LLM providers. Your agents talk to TapPass using an OpenAI-compatible API; TapPass talks to the real provider using the provider’s API key.

Your Agent                TapPass Gateway           LLM Provider
    │                          │                         │
    │  POST /v1/chat/          │                         │
    │  completions             │                         │
    │  Authorization:          │                         │
    │  Bearer tp_abc123        │                         │
    │ ─────────────────────►   │                         │
    │                          │  1. Authenticate agent  │
    │                          │  2. Run 49-step pipeline│
    │                          │  3. Policy check (OPA)  │
    │                          │  4. Resolve credentials │
    │                          │                         │
    │                          │  POST /v1/chat/         │
    │                          │  completions            │
    │                          │  Authorization:         │
    │                          │  Bearer sk-abc123       │
    │                          │ ──────────────────────► │
    │                          │                         │
    │                          │  ◄────── response ───── │
    │                          │                         │
    │                          │  5. Scan response       │
    │                          │  6. Audit log           │
    │  ◄──── response ──────   │                         │
    │                          │                         │

This means:

• Provider keys stay on the server. Agents never see sk-... keys.
• Governance is enforced server-side. Agents cannot bypass the pipeline.
• Key rotation is centralized. Rotate one place, all agents updated.
• Per-agent policies. Different agents can have different model access, budget caps, and data policies.

The 49-step pipeline

Every request and response passes through a configurable pipeline of governance steps. Steps run in order. Each step can inspect, modify, or block the request.

The pipeline is organized into phases:

Pre-LLM steps (before the request reaches the provider)

Category	Steps	What they do
Input validation	validate_input, posture_check	Schema validation, agent posture verification
Data protection	detect_pii, detect_secrets, pii_tokenize	Find and redact PII, API keys, passwords
Threat detection	detect_injection, detect_exfiltration, detect_escalation, detect_flooding, detect_social_engineering, detect_insider_threat, detect_boundary_escape, detect_unicode, detect_memory_poison	Prompt injection, data exfiltration, privilege escalation, social engineering
Tool governance	filter_tools, tool_permissions, tool_constraints, scan_tool_calls, verify_tool_governance, taint_check	Restrict tool access, enforce constraints, verify capability tokens
Content safety	content_safety, classify_data, inspect_images, detect_multimodal	Content moderation, data classification, image analysis
Rate limiting	rate_limit, budget_enforcement, session_budget	Per-agent and per-org rate limits, token budgets
Session controls	session_escalation, session_loop_guard, loop_guard	Detect agent loops, escalation patterns
Infrastructure	model_routing, detect_infra, detect_code_exec, shell_bleed	Model selection, infrastructure protection

LLM call

The call_llm step forwards the (potentially modified) request to the LLM provider through the credential vault.

Post-LLM steps (before the response reaches the agent)

Category	Steps	What they do
Output scanning	scan_output, scan_tool_results, redact_tool_results	Scan responses for PII, secrets, policy violations
Integrity	verify_claims, verify_artifact, dedup_output	Verify factual claims, check artifact integrity, deduplication
Restoration	pii_restore, constrain_output	Restore tokenized PII for authorized consumers, format constraints

Step configuration

Every step can be configured per-organization through policy:

{
  "steps": {
    "detect_pii": {
      "enabled": true,
      "on_detection": "redact",
      "threshold": 0.8
    },
    "rate_limit": {
      "enabled": true,
      "max_calls": 100,
      "window_seconds": 3600
    }
  }
}

Steps have four actions on detection: block (stop the request), redact (remove the sensitive content), notify (log and continue), or allow (skip).

Capability tokens

Capability tokens are signed, time-bound tokens that specify exactly what tools an agent can use and with what constraints. They implement the principle of least privilege for AI agent tool calls.

How they work

1. The control plane issues a token — specifying which tools, what constraints, and for how long.
2. The agent receives the token — attached to its session or passed per-request.
3. Tool executors verify offline — ~27 microseconds, no server round-trip needed.

Key properties

Property	Description
Proof-of-Possession (PoP)	Stolen tokens are useless without the holder’s private key
Monotonic attenuation	Delegated tokens can only narrow permissions, never expand them
Offline verification	Ed25519 signature check, no network call required
Rich constraints	Subpath, URL-safe, pattern matching, range limits, CEL expressions
Delegation chains	Up to 64 levels of cryptographically verified delegation
Trust scores	Agent reputation (0-1000) embedded in the token
Clearance levels	UNTRUSTED, EXTERNAL, PARTNER, INTERNAL, PRIVILEGED, SYSTEM

Token structure

┌─────────────────────────────────────────────┐
│ Capability Token (tp_ct_...)                │
├─────────────────────────────────────────────┤
│ issuer:     Ed25519 public key (32 bytes)   │
│ holder:     Ed25519 public key (32 bytes)   │
│ tools:      { "read_file": constraints }    │
│ clearance:  INTERNAL (30)                   │
│ trust_score: 750                            │
│ expires_at: 1711500000                      │
│ depth:      0 (root) / 1..64 (delegated)   │
│ parent_hash: SHA-256 link to parent token   │
├─────────────────────────────────────────────┤
│ signature:  Ed25519 over payload            │
└─────────────────────────────────────────────┘

Example: verification at tool executor

from tappass.capability_token import Authorizer, PublicKey

authorizer = Authorizer(trusted_roots=[control_plane_pubkey])
result = authorizer.check(token, "read_file", {"path": "/data/report.txt"}, pop_sig)

if result.authorized:
    # Execute the tool call
    ...
else:
    print(result.reason)  # "Tool 'read_file' not authorized"

Trust scoring

TapPass computes a health score for every agent based on its historical behavior. The score is computed from the audit trail — no new instrumentation needed.

Five dimensions

Dimension	Weight	What it measures
Compliance	30%	Pass rate without blocks
Data Safety	25%	PII and secret handling
Security	20%	Threat detection rate
Stability	15%	Behavioral consistency
Efficiency	10%	Cost management

How trust scores are used

• Capability token clearance. Trust score maps to clearance level — agents with scores below 200 get UNTRUSTED clearance, limiting tool access.
• Adaptive thresholds. Detection steps can use trust score to adjust sensitivity — trusted agents get lower false-positive rates.
• Dashboard visibility. The /agents/{agent_id}/health endpoint returns the score, grade (A-F), trend, and alerts.

Trust score to clearance mapping

Score range	Clearance	Meaning
950-1000	SYSTEM	Fully autonomous operation
800-949	PRIVILEGED	Trusted, minimal oversight
600-799	INTERNAL	Standard operation
400-599	PARTNER	Limited tool access
200-399	EXTERNAL	Restricted, monitored
0-199	UNTRUSTED	No tool access, observe only