Identity
Identity
Section titled “Identity”TapPass distinguishes three principal types, each with a distinct authentication mechanism, authorization scope, and privilege envelope.
The agent is the least-trusted component and is treated as such — it has no upward channel to escalate.
Per the privilege-separation model in governed-agents.md §13, TapPass's safety properties depend on these three identities being structurally separated.
At a glance
Section titled “At a glance”| Principal | Authenticates with | Privilege | Surface |
|---|---|---|---|
| Operator | SSO + MFA | High — defines policy at the appropriate cascade level | tappass CLI, dashboard |
| Host owner | Machine identity (mTLS cert) | Medium — applies policy locally | tappass-host daemon |
| Agent | Scoped sandbox token (5-min TTL, ES256) | Lowest — read-only consumer | tappass-agent SDK |
Operator
Section titled “Operator”The TapPass admin: CISO, project admin, or agent owner. Authors Policy at the appropriate Cascade level.
- Authentication: SSO + MFA via the customer's IdP.
- Authorization: scoped to the cascade level the operator owns. Org admins author the org floor; project admins author the project floor; agent owners author per-agent overrides; auditors get read-only views.
- Privileges: can author Policy, apply Compliance Packs, provision Sandbox-specs, mint Bootstrap URLs, run pre-deployment evaluation, view audit (within their scope).
- Surface: the
tappassmanagement CLI plus the dashboard.
Host owner
Section titled “Host owner”The DevOps person owning the machine where the agent runs. Owns the machine identity — that's what Sync trusts.
- Authentication: mTLS cert provisioned at enrollment, refreshed hourly.
- Authorization: can apply Compiled Policy received via signed Sync push to the local sandboxes it owns. Cannot author Policy. Cannot reach admin endpoints.
- Privileges: runs as a privileged daemon (namespace, Landlock, cgroup capabilities) so it can apply kernel-ring rules; drops privileges before exec'ing the agent.
- Surface: the
tappass-hostruntime daemon. CLI subcommands:init,start,stop,status,inspect,shell,logs.
The agentic application — the LLM-driven process that does the work. Read-only consumer of its own Compiled Policy. The least-trusted component.
- Authentication: scoped sandbox token (ES256-signed, 5-min TTL). The agent's tokens have no admin scope.
- Authorization: can call the LLM Gateway and MCP Broker within the capabilities the Compiled Policy permits. Cannot author Policy, modify the Compiled Policy, or escalate.
- Privileges: runs unprivileged. Reads its Compiled Policy from a read-only mount (
keyring.json) via inotify; never writes it. - No upward channel. There is no API on
tappass-agentthat asks TapPass for more capabilities. Sync is unidirectional. Enforced by:- Package design:
tappass-agentexposes no client classes for admin endpoints. - Transport: kernel-ring egress allowlist blocks anything not in the Compiled Policy's URL set.
- Authentication: the agent's tokens have no admin scope.
- Package design:
Sandbox identity vs. principal identity
Section titled “Sandbox identity vs. principal identity”A Sandbox has its own identity (sandbox_id, org_id, project_id). The Sandbox identity is what the audit trail attaches actions to. The Agent principal acts on behalf of one Sandbox — the principal token is bound to that Sandbox.
Multiple Sandboxes on the same host run under different agent principals (different UIDs, different namespaces, different tokens). Cross-sandbox isolation is enforced at every position — Compiled Policy, Sync channel, audit, capability tokens.
Sub-agent identity (derived)
Section titled “Sub-agent identity (derived)”When an agent spawns a sub-agent (e.g. an orchestrator delegating to a worker), the sub-agent gets a derived identity with strictly subset capabilities. Least-privilege delegation, automatic. The derivation chain is recorded in the Compiled Policy's identity.chain aspect.
Capability tokens
Section titled “Capability tokens”Operators, hosts and agents all hold ES256-signed tokens. Tokens carry a scope, a TTL (5 min for agent and host tokens; longer for operator session tokens), and are JWKS-verifiable offline.
| Token | TTL | Renewed by |
|---|---|---|
| Operator session token | per IdP policy | SSO refresh |
| Host mTLS cert | 1 hour | tappass-host re-auth |
| Bootstrap URL | 15 min, single-use | (burned on consumption) |
| Sandbox token (gateway / MCP) | 5 min | sync push from control plane |
If sync stops working, every capability token expires within minutes and the agent stops being able to act. Fail closed.
Attacker matrix
Section titled “Attacker matrix”A first-class attacker who owns the agent process cannot: modify the Compiled Policy, forge a sync payload, reach admin endpoints, replay older Compiled Policy versions, read other sandboxes. They can: use current tokens until expiry (~5 min), try denied tools (LLM Gateway rejects), trip loop_guard in the MCP Broker.
Engines that operate on Identity
Section titled “Engines that operate on Identity”| Engine | What it does | Status |
|---|---|---|
| SSO / MFA integration | Operator auth via customer IdP | concept (Q3 2026) |
| mTLS provisioning | Host identity at enrollment | concept (Q3 2026) |
| Token issuer (capability tokens) | ES256-signed sandbox tokens | shipped (tappass/gateway/) |
| JWKS publisher | Public keys for offline verification | shipped (tappass/gateway/) |
| Token revocation | Operator-driven; takes effect within next 5-min sync window | concept (Q3 2026) |
Surfaces
Section titled “Surfaces”| Persona | Surface | What you do |
|---|---|---|
| Operator | SSO login + MFA | authenticate to author Policy |
| Host owner | tappass-host init --enroll-url | accept bootstrap; receive mTLS cert |
| Agent | Keyring.load() from disk | read scoped token; cannot mint new ones |
| Auditor | dashboard view | inspect any sandbox's audit (within scope) |
Related concepts
Section titled “Related concepts”- scopes ↓ Capability token — the per-call authorization carrier
- bound to → Sandbox — agent identity acts on behalf of a sandbox
- delivered via → Bootstrap (host); SSO (operator); sync (agent token rotation)
- enforced by → Sync — the one-way signed channel that prevents agent escalation
Authoritative docs
Section titled “Authoritative docs”| Topic | File |
|---|---|
| Privilege separation model | governed-agents.md §13 |
| Three CLIs (one per principal) | governed-agents.md §14 + q14-three-clis/ |
| Capability tokens (shipped) | tappass/gateway/ — ES256, JWKS endpoint |
Common confusions
Section titled “Common confusions”- Identity ≠ Sandbox. A Sandbox is a logical agent installation; an Identity is who's authenticating. The Agent principal acts on behalf of a Sandbox.
- Three principals, not roles. Operator / Host / Agent are different kinds of identity (different auth mechanisms, different privilege envelopes). Within "Operator," there are roles (org admin, project admin, agent owner, auditor) — those are RBAC scopings, not separate principals.
- The agent has no upward channel. This is a hard architectural property, not a soft policy. The agent SDK cannot request more scope; sync is unidirectional. Without this property, "live policy" is unsafe.