Architecture
The Companion Agent is a single local service composed of cooperating modules. It sits inside the device's trust boundary and mediates between remote policy services and local hardware.
Component model
| Component | Responsibility |
|---|---|
| Loopback broker | Accepts requests from the viewer and browser on 127.0.0.1 with strict origin allowlisting. |
| Session manager | Maintains the authenticated IdP session and mints short-lived, audience-bound assertions. |
| Policy evaluator (PEP) | Evaluates cached and live policy against the requested action and returns Allow / Warn / Deny. |
| Device identity module | Generates and uses hardware-backed keys (TPM / Secure Enclave) and produces attestations. |
| Hardware interface | Drives smart-card and PKCS#11 middleware for CAC / PIV credentials. |
| Lease cache | Stores short-lived, device-bound policy leases for offline evaluation. |
| Audit logger | Signs each decision and buffers events locally until they can be synced. |
Trust boundaries
text
┌──────────────────────── Cloud control plane ────────────────────────┐│ Key Broker · Policy Decision Service · Trust registry · Audit sink │└───────────────────────────────┬──────────────────────────────────────┘ │ TLS · signed policy & leases┌────────────────────────────────▼─────────── Device trust boundary ───────────┐│ Companion Agent (PEP) ││ ├─ loopback broker (127.0.0.1, origin-allowlisted) ││ ├─ session manager ├─ policy evaluator ││ ├─ lease cache └─ audit logger (signed, buffered) ││ │ ││ ▼ ││ TPM / Secure Enclave · Smart Card (CAC/PIV) · Browser↔Viewer │└──────────────────────────────────────────────────────────────────────┘Everything below the device trust boundary stays on the endpoint. The cloud never receives plaintext and never holds a key that can decrypt documents on its own.
Request lifecycle
- Request - the viewer or a browser tab calls the loopback broker for access to a document.
- Identity - the session manager confirms an active user session and the device identity module attests the hardware-backed key.
- Evaluation - the policy evaluator checks permissions, device posture, and an active lease.
- Decision - a deterministic Allow / Warn / Deny verdict is returned, failing closed when trust evidence is missing.
- Audit - the audit logger signs the decision and buffers it for sync.
Deterministic by design
Given the same inputs - session, device state, policy, and lease - the Agent always produces the same verdict. This makes decisions reproducible and auditable.
Failure behavior
- Offline → evaluate against cached leases; deny when a lease expires.
- No device key → deny; the request cannot be bound to a trusted device.
- Untrusted origin → reject before any evaluation occurs.
- Tampered lease or policy → reject; signatures are verified before use.
See the security model for the full set of guarantees.