Security

TapPass is a security-critical component in the AI agent stack. This page describes the security architecture as implemented — every claim maps to code.

Authentication

One fail-closed middleware handles every request. Credentials are accepted via Authorization: Bearer, the X-API-Key header, or (for SSE only) an access_token query parameter.

Credential types

Type	Format	Use
Developer key	tp_dev_…	Agent/data-plane calls; hashed at rest; immutable agent identity; 365-day expiry
Personal access token	tp_pat_…	Control plane (CLI, automation); role capped live to the owner’s current org role
Session JWT	signed dashboard session token	Dashboard sessions; role refreshed live from membership
Admin bootstrap key	TAPPASS_ADMIN_API_KEY	Self-hosted bootstrap; constant-time comparison
MCP OAuth token	kid=mcp-v1 JWT	OAuth 2.1 access tokens for the MCP server (dynamic client registration supported)

With no admin key configured (local dev), the server auto-authenticates as a local org_admin — convenient locally, refused in production mode.

SSO

• OIDC — Google and multi-tenant Microsoft Entra ID (/sso/login → /sso/callback → /sso/exchange), with domain allowlisting. See Identity integrations.
• SAML 2.0 — TapPass as Service Provider, signed assertions/responses enforced by default, IdP metadata or manual config.
• Per-agent request signing — optional per-agent request-signature verification.

Origin verification

When TAPPASS_ORIGIN_SECRET is set, every request must carry a matching X-Origin-Verify header — e.g. behind Cloudflare, so only traffic through your edge reaches the server.

Authorization

RBAC roles

Role	Can
employee	Chat, own sessions
developer	Agent keys, governed calls, audit read for own org
auditor	Full audit read, integrity verification, evidence export
org_admin	Org settings, members, policies, keys
super_admin	Cross-org platform operations

Roles are per-organization and enforced per route; role lookups are live (a demotion takes effect on the next request, not the next login).

Capability tokens & mandates

Fine-grained, per-action authorization is cryptographic: cryptographic capability tokens (offline-verifiable, non-replayable, attenuation-only) and short-lived mandates minted on allow verdicts. See Architecture and verdicts & mandates.

Policy engine

Authorization decisions are made by an in-process policy evaluator; per-agent content-addressed bundles; evaluation is pure, deterministic, fail-closed: any bundle read/eval error blocks the call.

Data encryption

In transit

TLS 1.2+ on all external communication (agent → TapPass, TapPass → provider).

At rest

Data	Protection
Provider & tool credentials	encrypted at rest in the vault; per-org isolation; plaintext only in memory at execution
Vault master key	KMS envelope: aws_kms://, gcp_kms://, azure_kv://, vault://, or CyberArk Conjur
Audit trail	Integrity via hash chain + hybrid signatures (below); database-level encryption per deployment
API keys	hashed at rest

Key management

• Audit signing keys — loaded from TAPPASS_AUDIT_SIGNING_KEY (optionally password-encrypted) or generated into TAPPASS_KEYS_DIR.
• Token signing keys — loaded from TAPPASS_TOKEN_KEY_FILE.
• Sensitive config supports _FILE variants for Docker secrets.

Audit trail integrity

Three independent layers of tamper protection; see the audit trail for the full model.

1. Per-org hash chain (v2). Each event’s hash covers its canonical fields plus the prior event’s hash; concurrent writers are serialized per org. Modification, deletion, or insertion breaks every subsequent link.

2. Hybrid signatures. Every event is dual-signed with a classical + post-quantum scheme — both signatures must verify. Public keys are published at GET /api/audit/signing-key for independent external verification.

3. Checkpoint anchoring. Signed checkpoints record chain head, event count, and timestamp — an independent witness that survives full-chain replacement attempts.

Verifying

curl -H "Authorization: Bearer tp_..." \
  "https://tappass.example.com/api/audit/integrity"
# {"status": "intact", "chain_length": …, "broken_events": []}

Security posture

Principle	Implementation
Fail-closed	Auth, policy, producer, and obligation failures block. The one documented exception: rewrite_response is fail-open.
No hidden policy	The kernel composes no hardcoded floor — every block traces to an activated rule.
Constant-time comparison	Admin key and secret comparisons are constant-time.
No secrets in logs	Structured logging with redaction; TAPPASS_AUDIT_LOG_PARAMS off by default.
Lockout	Failed-auth lockout: 5 attempts / 300 s window → 900 s lock (configurable).
Rate limiting	Per-key and per-org request/token limits, enabled by default.
SSRF guard	SIEM/webhook destinations reject loopback, private, and metadata IPs.
Production gate	TAPPASS_ENV=production refuses to boot without admin key, strong JWT secret, vault key, and token key file.

Vulnerability disclosure

1. Do not open a public GitHub issue.
2. Email security@tappass.ai with a description and reproduction steps.
3. We acknowledge within 48 hours and work with you on scope and fix.
4. We credit reporters in the advisory (unless you prefer anonymity).

We follow coordinated disclosure and ask for 90 days before public disclosure.