Security

TapPass is a security-critical component in the AI agent stack. This page describes the security architecture that protects agent-to-LLM communication.

Authentication

TapPass supports multiple authentication methods depending on deployment context.

API keys

The simplest method. Your platform team issues tp_ prefixed API keys:

Authorization: Bearer tp_abc123...

API keys identify the agent and its organization. They are validated on every request before the governance pipeline runs.

OAuth 2.0

For production deployments with identity providers (Okta, Auth0, Entra ID):

• Authorization Code flow for interactive applications
• Client Credentials flow for service-to-service (agent-to-TapPass)
• Token introspection and JWT validation

SAML 2.0

For enterprise SSO integration. TapPass acts as a SAML Service Provider, supporting IdP-initiated and SP-initiated flows.

SPIFFE / SPIRE

For workload identity in Kubernetes and service mesh deployments:

• SPIFFE Verifiable Identity Documents (SVIDs) — X.509 certificates issued by SPIRE
• Mutual TLS — both agent and TapPass verify each other’s identity
• Zero-trust networking without shared secrets

SPIFFE is the recommended authentication method for production Kubernetes deployments.

Authorization

TapPass uses a layered authorization model combining Role-Based Access Control (RBAC) with capability tokens.

RBAC roles

Role	Permissions
AGENT	Make governed LLM calls, read own audit trail
DEVELOPER	Register agents, configure flags, read own org’s audit
ADMIN	Manage organization settings, users, policies
AUDITOR	Read all audit events, verify integrity, export evidence
PLATFORM	Full access including provider configuration and break-glass

Roles are assigned per-organization. A user can have different roles in different organizations.

Capability tokens

For fine-grained tool-level authorization, TapPass uses cryptographic capability tokens. See Architecture — Capability Tokens for details.

Key properties:

• Signed with Ed25519 — tokens cannot be forged
• Proof-of-Possession — stolen tokens are useless without the holder’s private key
• Monotonic attenuation — delegated tokens can only narrow permissions
• Offline verification — ~27 microseconds, no server round-trip

OPA policy engine

All authorization decisions are made by an embedded Open Policy Agent (OPA) instance. Policies are written in Rego and cover:

• Which agents can access which models
• Which tools an agent can invoke
• Budget and rate limit enforcement
• Break-glass authorization
• Data classification-based access control

Data encryption

In transit

All communication is encrypted with TLS 1.2+:

• Agent to TapPass — TLS with server certificate validation (mutual TLS with SPIFFE)
• TapPass to LLM provider — TLS to provider endpoints
• Internal services — mTLS between TapPass components in distributed deployments

At rest

Data	Encryption
Provider API keys	AES-256-GCM in the credential vault, with tenant isolation
Audit trail	Database-level encryption. Event signatures provide integrity.
Local audit buffer (SDK)	AES-256-GCM when TAPPASS_AUDIT_BUFFER_KEY is set
Configuration	Sensitive fields encrypted in the database

Key management

• Provider credentials are stored in the credential vault, which supports HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, and CyberArk backends.
• Audit signing keys are Ed25519 keys, loaded from file (TAPPASS_AUDIT_SIGNING_KEY) or generated at startup.
• Token signing keys are Ed25519 keys used for capability token issuance.

Audit trail integrity

The audit trail uses three independent layers of tamper protection:

1. Hash chain

Every audit event includes the SHA-256 hash of the previous event. The hash covers all event fields plus the previous hash, creating an append-only chain.

Event 1 ──hash──► Event 2 ──hash──► Event 3 ──hash──► ...
         (prev=0x00..00)   (prev=hash(E1))   (prev=hash(E2))

Tampering breaks the chain:

• Modify an event — hash mismatch at the next event
• Delete an event — gap in the chain linkage
• Insert a forged event — hash will not match unless the attacker has the full chain

2. Event signatures

Each event is signed with the server’s Ed25519 key. Even if an attacker can access the audit file, they cannot sign forged events without the private key.

The public key is exposed at /audit/signing-key so external verifiers can check signatures independently.

3. Checkpoint anchoring

Every N events, a signed checkpoint is written to the database containing the chain head hash, event count, and timestamp. This creates an independent witness that survives full chain replacement attacks.

Verifying integrity

# Full integrity check (requires AUDITOR role)
curl -s -H "Authorization: Bearer tp_abc123..." \
  "https://tappass.example.com/audit/integrity"

See Compliance Evidence for SOC 2 evidence generation.

Security posture

TapPass follows these security principles in its implementation:

Principle	Implementation
Fail-closed on auth/policy	Authentication and policy failures block the request. Never fail-open on security decisions.
Constant-time comparison	All secret comparisons use constant-time algorithms to prevent timing attacks.
No secrets in logs	Structured logging via structlog with automatic secret redaction. Errors truncated at 200 characters.
Atomic file writes	All file writes use temp file + rename to prevent partial writes.
One-way ratchet on sandbox	Sandbox restrictions can only increase, never decrease during a session.
Thread-safe shared state	All shared mutable state protected by threading.Lock with double-checked locking.

Vulnerability disclosure

If you discover a security vulnerability in TapPass, please report it responsibly:

1. Do not open a public GitHub issue.
2. Email security@tappass.ai with a description of the vulnerability.
3. Include steps to reproduce if possible.
4. We will acknowledge receipt within 48 hours.
5. We will work with you to understand the scope and develop a fix.
6. We will credit you in the security advisory (unless you prefer anonymity).

We follow coordinated disclosure: we ask that you give us 90 days to address the issue before public disclosure.