tegwick
bc49a24c4c
Vault path prod/binky/company-email/imap, secrets-engine catalog draft, email-connect read-only IMAP wiring. Credential handover stays a single Red-lane founder step. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
# 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.
|