# Company Email → Net Kingdom / OpenBao Integration Plan

> Status: prepared v1 — 2026-07-16 (BINKY-WP-0003-T01, AWQ-007).
> Goal: `bernd.worsch@binky-hedgehog.com` becomes an agent-readable event
> source so StB replies, bank and authority notices reach the control plane.
> **Credential handover is a single Red-lane founder step at the end** — no
> agent solicits or stores the password before the vault lane exists.

## Architecture (sanctioned path)

Per `net-kingdom/docs/secrets-engine-security-infrastructure-boundary.md`:
OpenBao owns custody/policy/audit; **secrets-engine** owns the workflow
(catalog → decision → plan/apply → provisioning → exec-time delivery);
**email-connect** is the consumer (read-only IMAP mailbox scan, MVP already
supports `mailbox.protocol: imap` with credential *environment variable
names* in config — values never in config files).

```text
founder (Red lane, once)
   └─ provisions IMAP password into OpenBao via secrets-engine plan
        └─ OpenBao kv: secret/prod/binky/company-email/imap
             └─ secrets-engine exec --catalog binky-company-email-imap \
                    -- python -m email_connect.cli scan-mailbox ...
                  └─ scan reports / classified evidence → binky-control queues
```

## Draft secrets-engine catalog entry (non-secret)

To be landed in `~/secrets-engine/catalog/binky-company-email-imap.yaml`
after review (kept here as the reviewed source until then):

```yaml
id: binky-company-email-imap
org: binky
repo: binky-control
stage: prod
description: >-
  IMAP credentials for the company mailbox bernd.worsch@binky-hedgehog.com.
  Read-only mailbox scanning by email-connect so real-world events (StB
  replies, bank/authority notices) reach the Binky control plane.

mount: secret
path: prod/binky/company-email/imap

fields:
  - imap_username
  - imap_password

consumers:
  - name: email-connect-scanner
    auth: approle
    claim: "role:email-connect-scanner"
    purpose: "read-only IMAP scan of the company mailbox"

delivery_modes:
  - exec-env        # secrets-engine exec injects IMAP_USERNAME/IMAP_PASSWORD

approval:
  model: decision   # State Hub decision + founder handover (Red lane)
  notes: "Founder provisions the value once; agents never see or relay it."

verification:
  positive: "email-connect scan-mailbox completes a read-only folder scan"
  negative: "no other consumer role can read prod/binky/* paths"

rotation:
  expectation: "on suspicion or provider change; founder-triggered"

deactivation:
  expectation: "disable AppRole + delete kv path if mailbox is migrated"

audit:
  evidence: "actor, path, timestamp, result — no secret value"
```

Non-secret connection facts still to confirm with the founder (Blue lane,
not credentials): IMAP host/port for the binky-hedgehog.com mail provider,
folder to scan (default INBOX).

## email-connect consumer config (non-secret, draft)

```yaml
mailbox:
  protocol: imap
  host: <provider-imap-host>        # TODO: confirm provider
  port: 993
  folder: INBOX
  username_env: IMAP_USERNAME
  password_env: IMAP_PASSWORD
```

Scan output (CSV evidence reports) initially lands in this repo under
`mailmeta/` (metadata only — no message bodies in git); triage routes items
into DecisionQueue / OfficeHourQueue / RiskRegister, receipts toward DUO
Belegablage (shared triage step with paper mail, AWQ-008).

## Execution checklist

1. [x] Vault path + catalog entry designed (this document)
2. [ ] Confirm IMAP host/provider facts with founder (non-secret)
3. [ ] Land catalog entry in `secrets-engine/catalog/`; register decision in
       State Hub (approval model `decision`)
4. [ ] Verify OpenBao prod reachability from the executing machine
       (workstation has no local OpenBao on :8200 — prod custody lives in
       the NetKingdom deployment; check via secrets-engine roles)
5. [ ] **Red lane — founder, once:** provision the IMAP password through the
       secrets-engine provisioning flow (never via chat/prompt/file)
6. [ ] First read-only scan via `secrets-engine exec … scan-mailbox`;
       file evidence report; add triage step to OperatingRhythm
7. [ ] Recurring scan becomes an activity-core definition (see T05) and an
       llm-connect execution target (see T06)

## Boundary rules (binding)

- Secret values never appear in git, State Hub, chat, prompts, logs, or
  workplans — catalog metadata only.
- email-connect stays read-only (`BODY.PEEK`); no mailbox write-back.
- Sending mail from the company address is out of scope here; it would be a
  separate catalog lane and a separate decision.