qonto-assistant/docs/SecurityPractice.md

# Security Practice — Internet Exposure, Governance, and Scale-to-Zero

> Status: draft, 2026-07-23. Written before deployment to `railiance01`.
> Context: this is the first fleet service that (a) must be reachable by
> clients outside the cluster (laptop-based Claude Code/Cursor/Codex
> sessions), and (b) is the sole holder of a real company bank credential.
> That combination raises the risk class above every other agent-facing
> service shipped so far (`llm-connect`, mail-triage), which are
> cluster-internal only.

Related: `specs/ArchitectureBlueprint.md` (service architecture and v1
policy), `docs/mcp-integration.md` (current auth model and its called-out
gaps), `docs/operator-runbook.md` (day-2 operation).

This document assumes the [`kings-guard`](../../kings-guard) NetKingdom
Immune Architecture exists as designed in
`kings-guard/specs/NetKingdomImmuneArchitecture.md` (currently draft, no
implementation) and describes how `qonto-assistant` would sit inside it,
alongside the real, already-running NetKingdom components (`key-cape`,
`flex-auth`, `tenant-engine`, OpenBao/`ops-warden`). Concrete requirements
handed to `kings-guard` to prioritize its own build are tracked as an
intake — see `KG-WP-0002` and the corresponding intake record.

---

## 1. Why this service is a different risk class

| Property | Prior services (`llm-connect`, mail-triage) | `qonto-assistant` |
| --- | --- | --- |
| Client population | in-cluster jobs/timers only | in-cluster **and** external harness sessions (laptops) |
| Network exposure | cluster-internal DNS only | needs a real internet-reachable address |
| Credential held | none / low-value | live company bank API key (`tenants/binky/qonto-api`) |
| Data classification | operational metadata | tenant-confidential financial data |
| Blast radius if compromised | mail queue drift | real financial data disclosure; reputational and possibly regulatory impact |

Every control below exists to answer one question: **what stops an
internet-reachable process, holding a real bank credential, from becoming
the fleet's first genuinely damaging incident?**

---

## 2. Layered design

```text
Internet
   │
   ▼
┌─────────────────────────────────────────────────────────────┐
│  Facade / Activator  (always-on, holds NO bank credential)  │
│  - key-cape token verification                              │
│  - flex-auth pre-check (finance.qonto.read)                  │
│  - wakes the real service only after both pass                │
│  - idle-timeout scale-back-to-zero                            │
└───────────────────────────┬───────────────────────────────────┘
                            │ (only on authenticated+authorized wake)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  qonto-assistant  (scaled 0↔1, isolation profile I1/I2)      │
│  - policy kernel (default-deny; existing, unchanged)         │
│  - REST + MCP surfaces (existing, unchanged)                  │
│  - OpenBao fetch on cold start only, short TTL                │
│  - audit emission shaped as Kings Guard Immune Observations   │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            ▼
                    OpenBao (tenants/binky/qonto-api)
                            │
                            ▼
                      Qonto thirdparty API
```

The facade and the scale-to-zero controller are **the same component**.
Building it once satisfies both the cost concern (service is idle most of
the time and should not burn compute) and the security concern (nothing
reachable from the internet is allowed to trigger a cold start of the
credential-holding process without first clearing identity and
authorization checks). This is deliberate: a "wake on any request" facade
without the auth gate would just be a new, free DoS/cost-exhaustion lever.

---

## 3. Identity — replace the interim bearer token with `key-cape`

`docs/mcp-integration.md` already documents today's interim state: a
shared-secret bearer token (`QONTO_ASSISTANT_MCP_TOKEN`) stands in for real
workload/client identity, explicitly because "no OIDC issuer exists in this
fleet yet."

That premise no longer holds for this deployment. `key-cape`
(Authelia + LLDAP + privacyIDEA) is the fleet's real, already-running IAM
Profile issuer — it is SSO today for ops/Temporal UI (`NK-WP-0021`). Before
`qonto-assistant` is internet-facing:

- The facade verifies a `key-cape`-issued IAM Profile token (human operator
  session or service/workload identity) on every inbound request, before
  any wake decision.
- The shared-secret `QONTO_ASSISTANT_MCP_TOKEN` becomes fixture/local-dev
  only (as already documented) and must never be the auth boundary for a
  real deployment.
- Actor claims (`X-Actor-ID`, `X-Tenant-ID`, `X-Actor-Lane`, `X-Actor-Scopes`)
  stop being self-asserted headers and are instead derived from the
  verified token — closing the gap `docs/mcp-integration.md` §Auth model
  calls out explicitly ("self-asserted today, not cryptographically bound").

## 4. Authorization — register `finance.qonto.read` in `flex-auth` now

`config.py` already reserves `QONTO_ASSISTANT_REQUIRED_SCOPE` /
`QONTO_ASSISTANT_ENFORCE_SCOPE` for exactly this and ships with enforcement
off. Given internet exposure, this should not wait for "Phase 3" — it is
the actual authorization control point standing between an authenticated
caller and a live bank-data read.

- Register `finance.qonto.read` (and, if useful later, a narrower
  `finance.qonto.read.transactions` / `.export`) as a `flex-auth` resource.
- The facade (or the assistant itself, on cold-start request) calls
  `flex-auth` for a live decision rather than trusting a cached claim for
  this resource class — mirroring the same reasoning `tenant-engine`
  applies to itself: *"a stale `VEN` grant surviving a plan cancellation is
  not an acceptable risk for money-movement or credential-vending
  actions"* — read-only finance visibility deserves the same live-check
  discipline, not just write paths.
- Gate on **live tenant capability role** via `tenant-engine`
  (`VEN`/`CUS`, non-exclusive) and plan, replacing the current hardcoded
  `default_tenant_id="binky"` assumption in `config.py`. A tenant whose
  plan lapses should lose read access the same request cycle, not whenever
  a cache expires.

## 5. Network exposure — the facade is the only internet-facing thing

`qonto-assistant`'s raw REST/MCP port must never be bound to a
publicly-reachable address, in any deployment. Concretely:

- The Kubernetes `Service`/ingress in front of `qonto-assistant` itself
  should remain cluster-internal (`ClusterIP`), matching the pattern
  `railiance-rhythm`'s host timers already use for `llm-connect`.
- The facade is the sole component with an external address. It is
  deliberately dumb: no policy kernel, no bank credential, no Qonto client
  — its only job is auth-gate, wake, proxy, and idle-timeout.
- Failure mode: if `key-cape` or `flex-auth` is unreachable, the facade
  **fails closed** (refuses to wake the backend), per Kings Guard principle
  6.11 ("fail securely, not blindly") — an outage in the auth path must not
  silently become an open-access mode.

## 6. Scale-to-zero — cost control and security control together

- Facade holds the public address; backend `Deployment` runs at `replicas:
  0` when idle.
- On an authenticated+authorized request, facade scales the backend to 1,
  waits on `GET /v1/health`, then proxies through.
- An idle-timeout watcher (same component or a sidecar) scales back to 0
  after a configurable window (proposed default: 10–15 minutes of no
  traffic) — tunable per deployment, not hardcoded.
- If the target cluster already runs Knative Serving, this is close to the
  built-in Activator + scale-to-zero autoscaler pattern and should reuse it
  rather than reinventing one. Otherwise a minimal custom
  controller is small and narrow in scope (one Deployment, one Service,
  one wake/idle state machine) and should be scoped as its own follow-on
  task rather than folded into `qonto-assistant`'s own codebase — see
  `QONTO-WP-0004`.
- Security side effect, not just a cost one: because OpenBao secret fetch
  already uses a short TTL (`qonto_secret_ttl_seconds`), scale-to-zero
  shrinks the bank credential's residency window in process memory to
  "only while an authenticated request is actually being served" — smaller
  than today's always-on posture, for free.

## 7. Isolation profile

Per `kings-guard`'s isolation-profile classification
(`NetKingdomImmuneArchitecture.md` §11), given:

- tenant-confidential financial data classification,
- internet reachability (via the facade),
- sole custody of a real bank credential,

`qonto-assistant` should run at **I1 Reinforced** at minimum (dedicated
node pool or sandboxed runtime) rather than the shared/logical-isolation
default (I0) other low-risk internal services use. **I2 Dedicated**
(tenant-specific control/compute plane) is worth considering given it is
the single component in the fleet holding this particular credential — the
decision belongs to whoever owns Railiance placement for this workload, not
to this repo alone.

## 8. Recovery

`qonto-assistant` already has the properties Kings Guard's "recovery is a
first-class capability" principle (AD-006) asks for, largely as a side
effect of how it was built, not extra work:

- **Stateless** — no persisted secrets or session state; redeployable at
  any time.
- **Short-TTL credential** — OpenBao lease expires quickly; a fresh pod
  fetches its own, it never inherits a stale one.
- **Cheap reconstitution** — "kill the pod, let the facade cold-start a
  fresh one on the next legitimate request" is a complete, low-cost
  recovery procedure with no data-loss risk (`maximum_data_loss: PT0S`
  applies trivially since there is no persisted data).

## 9. King's Guard observation mapping

King's Guard has observed the structured allow/deny stream. The source keeps
ownership of its genome and emission claims; the observer independently checks
the records and completeness evidence it receives.

### 9.1 Security Genome record

See `specs/security-genome.yaml` for the concrete record following
`NetKingdomImmuneArchitecture.md` §9.1's schema — declared purpose,
capabilities provided/consumed, expected egress (Qonto API + OpenBao only,
nothing else), data classification, and recovery expectations.

### 9.2 Audit stream is already observation-shaped

`AuditLogger`'s event shape includes actor, capability, decision, deny reason,
latency, upstream HTTP status, policy version, identity binding, and egress
destination (see `tests/test_audit.py`, `tests/test_audit_parity.py`). Every
record also carries a process-instance id and monotonic stream sequence.

The source-owned declaration in `specs/audit-emission-cadence.yaml` classifies
`audit.deny` as load-bearing and low-volume. A startup heartbeat, periodic
heartbeat (24 hours by default), and best-effort shutdown heartbeat publish
cumulative and window transition counts. Consumers compare those counts and
sequence continuity with observed records. `/v1/audit/reconciliation` exposes
the same non-secret current source counts for an authenticated diagnostic read.

### 9.3 A concrete, actionable-today signal

This does not require any Kings Guard component: repeated
`arg_constraint` or `credential_exfil` deny reasons from the same actor
within a short window is a real, current signal. It should trip a
tightened rate limit or a temporary lockout for that actor now. The current
`DenyEscalationTracker` branches directly on the same decision path that emits
the audit event; it does not consume the audit stream. This is a Fast Local Loop
(`NetKingdomImmuneArchitecture.md` §14.1) response that does not need to wait
for any future component, while the stream remains load-bearing for estate
observation rather than for the local lockout.

---

## 10. What this repo can do unilaterally vs. what it depends on

| Item | Owner | Status |
| --- | --- | --- |
| Security Genome record | `qonto-assistant` | can ship now |
| Audit-stream shape review against Immune Observation contract | `qonto-assistant` | can ship now |
| Actor lockout on repeated deny signals | `qonto-assistant` | can ship now |
| `key-cape` token verification in place of bearer token | `qonto-assistant` + `key-cape` | verifier shipped; live enforcement is runtime-configured |
| `finance.qonto.read` resource + live decision call | `qonto-assistant` + `flex-auth` | client and policy shipped; live use is runtime-configured |
| Live tenant-role gate | `qonto-assistant` + `tenant-engine` | client shipped; live use requires a reachable deployment URL |
| Facade / scale-to-zero activator | new component (home TBD — Railiance or a dedicated repo) | design only so far |
| I1/I2 isolation placement on `railiance01` | Railiance | needs a placement decision |
| Audit-stream observation and completeness acceptance | `kings-guard` | consuming events; cadence/reconciliation acceptance pending |

Tracked as `QONTO-WP-0004` in this repo, with the `kings-guard`-owned
portion tracked as an intake against `KG-WP-0002` (pilot-lane selection).