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

# Company Email → Net Kingdom / OpenBao Integration Plan

> Status: lane active — provision done — 2026-07-17 (WARDEN-WP-0028).  
> 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** — no agent solicits
> or stores the password before provision.

## Architecture (sanctioned path)

| Layer | Role |
| --- | --- |
| OpenBao mount **`tenants/`** | Custody for client/tenant commercial secrets |
| railiance-platform **CCR-2026-0007** | Policy + OIDC role (applied); value provision separate |
| ops-warden catalog **`binky-company-email-imap`** | Front door (`warden access`); no custody |
| email-connect | Read-only IMAP scan; credentials only via env *names* |
| binky-control | Queues + `mailmeta/` metadata evidence (no message bodies in git) |

```text
founder (Red lane, once)
   └─ bao kv put tenants/binky/company-email/imap IMAP_USERNAME=@file IMAP_PASSWORD=@file
        └─ OpenBao: tenants/binky/company-email/imap
             └─ warden access binky-company-email-imap --out / --exec
                  └─ email-connect scan-mailbox → mailmeta / queues
```

## Provider facts (IONOS — non-secret)

Source: IONOS Mail connection tables (founder 2026-07-17).

### Inbound (we use IMAP)

| Setting | IMAP | POP3 (unused) |
| --- | --- | --- |
| Server | `imap.ionos.de` | `pop.ionos.de` |
| Port | `993` | `995` |
| Encryption | SSL/TLS | SSL/TLS |

### Outbound SMTP (out of scope for this lane)

| Setting | SMTP |
| --- | --- |
| Server | `smtp.ionos.de` |
| Port | `465` |
| Encryption | SSL/TLS |

### Login shape (IONOS)

| Field | Value |
| --- | --- |
| Username | Full mailbox address (e.g. `bernd.worsch@binky-hedgehog.com`) |
| Password | Mailbox password for that address |

Username is not a high-secrecy secret but still lives in OpenBao with the
password so consumers get one fetch surface. **Password never in git/chat.**

## OpenBao lane

| Item | Value |
| --- | --- |
| Mount | `tenants` |
| Path | `tenants/binky/company-email/imap` |
| Fields | `IMAP_USERNAME`, `IMAP_PASSWORD` |
| Policy | `workload-kv-read-binky-company-email-imap` |
| OIDC role | `binky-company-email-imap-workload-kv-read` |
| Catalog | `binky-company-email-imap` (active, resolvable) |
| Risk | high |

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

Repo copy: `integrations/mailbox-binky-company.yml` (host/port/env names only).

```yaml
mailbox:
  id: binky-company-primary
  protocol: imap
  host: imap.ionos.de
  port: 993
  tls: true
  folder: INBOX
  username_env: IMAP_USERNAME
  password_env: IMAP_PASSWORD
```

Scan output under `mailmeta/` — metadata only (no message bodies in git).

## Execution checklist

1. [x] Path convention decided (`tenants/<tenant>/…`) — WARDEN-WP-0028
2. [x] Mount `tenants/` enabled on bao.coulomb.social
3. [x] CCR-2026-0007 + policy + OIDC role applied (metadata only)
4. [x] ops-warden draft catalog + playbooks
5. [x] Confirm IMAP host/provider facts (IONOS: `imap.ionos.de:993` SSL/TLS)
6. [x] **Red lane — founder:** provision username/password via `@file` only
7. [x] Capabilities-safe verify + promote catalog to active/resolvable
8. [x] First read-only scan 2026-07-17: 93 messages, evidence CSV in
       `mailmeta/reports/` (scan c3c7e784…). Notable: Stripe webhook
       failure notice, Qonto Beleg reminders, HUB31 correspondence,
       2 suspicious external mails (ignored, never acted on)
9. [~] Recurring scan via activity-core (BINKY-WP-0004 T05): fully wired —
       `executor-worker mail-scan` (deterministic scan phase: AppRole or
       ambient bao token → email-connect read-only → hub
       `binky_mail_intake` event on success only) + triage session spec
       (`~/executor-worker/examples/task-binky-mail-triage.json`, includes
       the suspicious-mail log-only rule). Goes live once the founder
       provisions the Lane 3 AppRole
       (`integrations/executor-worker-secrets.md`) and T06 enables
       `binky-weekly-mail-intake`.

### Founder provision (step 6) — interactive human shell

```bash
bao login -method=oidc -path=netkingdom role=binky-company-email-imap-workload-kv-read

# write mailbox address and password to mode-0600 files (never paste into chat)
umask 077
printf '%s' 'bernd.worsch@binky-hedgehog.com' > /tmp/imap.user
# password into /tmp/imap.pass via editor or paste in a private terminal only

bao kv put tenants/binky/company-email/imap \
  IMAP_USERNAME=@/tmp/imap.user \
  IMAP_PASSWORD=@/tmp/imap.pass
shred -u /tmp/imap.user /tmp/imap.pass
```

Then tell the agent/session so catalog can promote and the first scan can run.

## Boundary rules (binding)

- Secret values never appear in git, State Hub, chat, prompts, logs, or workplans.
- email-connect stays read-only (`BODY.PEEK`); no mailbox write-back.
- Agents with `WARDEN_AGENT_ID` set must not stream raw high-risk values.
- **SMTP / sending** from the company address is a **separate** future lane
  (`smtp.ionos.de:465`); not this CCR.

## See also

- `integrations/mailbox-binky-company.yml`
- ops-warden `wiki/playbooks/binky-company-email-imap.md`
- ops-warden `wiki/playbooks/tenant-secret-onboarding.md`
- railiance-platform `credential-change-requests/CCR-2026-0007-binky-company-email-imap.yaml`