# Bascule — Governed Shell Access Control

Bascule is an SSH-over-HTTPS proxy with identity-aware sessions and
ceremony-gated access control. It terminates operator identity (SSH certs,
OIDC tokens, Entra), evaluates Accord policy, classifies sessions by the
host's hardware attestation posture, and emits Chronicle audit events for
every governed operation.

## Component Map

```
Operator
  │
  ▼
bascule-gateway (cluster-side gRPC)
  ├─ OIDC auth → OperatorIdentity
  ├─ Ceremony engine (self-grant / single-approval / break-glass)
  ├─ Posture-current ConfigMap → ShellClass derivation
  ├─ OPA policy evaluation (via accord-opa)
  ├─ 8-stage filter chain (auth→session→classify→policy→budget→execute→response→audit)
  ├─ Breach evaluator (30s posture poll, BreachResponse enforcement)
  └─ Audit pipeline → Quartermaster merkle anchoring
  │
  ▼
bascule-agent (application sidecar)
  ├─ Shellstream protocol (msgpack over Unix socket)
  ├─ 8 namespace handlers (Crypto, Identity, Secrets, Governance,
  │   Attestation, Audit, Network, Intelligence)
  ├─ PostureReader → posture-current ConfigMap (cached, 30s TTL)
  └─ Optional SSH server on port 2222

bascule-core (shared types)
  ├─ SessionScope, ShellClass, DelegationScope
  ├─ CeremonyGrant, CeremonyType, Evidence
  ├─ derive_shell_class(PostureLevel) → ShellClass
  └─ BreachAction evaluation
```

## Keylime Integration Model

Bascule **consumes** Keylime attestation — it does not reimplement or
compete with it. The integration boundary is the `posture-current`
ConfigMap written by the substrate-operator's posture evaluator:

```
Keylime verifier (CNCF)
  → substrate-operator / TpmAttestationValid checker
    → posture-current ConfigMap (level: 1-5)
      → bascule-agent PostureReader
      → bascule-gateway ceremony grant (ShellClass derivation)
      → bascule-gateway breach evaluator (session downgrade)
```

The `keylime-client` crate (in the substrate workspace) is the single
Keylime consumer. Neither bascule-agent nor bascule-gateway imports it
directly. They read the ConfigMap output.

## ShellClass Model

Sessions are classified at ceremony grant time based on the host's
operational posture level:

| PostureLevel | ShellClass | Operations Permitted |
|---|---|---|
| Normal (5) | System | Kernel modules, firmware, network config, storage |
| Elevated (4) | Application | Deploy, query APIs, run playbooks |
| Restricted (3) | Application | Deploy, query APIs, run playbooks |
| Critical (2) | Application | Deploy, query APIs, run playbooks |
| Lockdown (1) | Application | Deploy, query APIs, run playbooks |

- No mid-session upgrade. Downgrade only (on posture breach).
- Upgrade requires a new ceremony.
- DelegationScope enables "Infrastructure shells" — Application sessions
  that orchestrate System operations on remote hosts (Ansible pattern).

## What's Implemented vs Planned

| Component | Status |
|---|---|
| Ceremony engine (3 types) | Implemented |
| 8-stage filter chain | Implemented |
| PostureReader (ConfigMap) | Implemented |
| ShellClass derivation | Implemented |
| DelegationScope + pre-flight | Implemented (target posture query stubbed) |
| Breach evaluator + downgrade | Implemented |
| Accord hot-reload | Not implemented (static at startup) |
| Helm chart | Exists, not updated for posture fields |
| LabelSelector delegation | Type defined, async resolution deferred |

## License

Apache-2.0. All source files carry SPDX headers.