binky-control/integrations/company-email-openbao.md

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).

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):

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)

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. 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.