# inbound-library IMAP entry

This is a sibling of the telemetry SMTP entry (`docs/telemetry-smtp-custody.md`).
It follows the same pattern and makes the same guarantees. The work belongs to
inbound-library ILIB-WP-0002-T07. The founder requested the entry on 2026-10-05
for the dedicated mailbox library@coulomb.social and will add the password.

KV v2 mount: `platform`. Entry: `workloads/inbound-library/imap`.
Full CLI path: `platform/workloads/inbound-library/imap`.

The initial fields are:

| Field | Value |
| --- | --- |
| `IMAP_HOST` | `imap.ionos.de` |
| `IMAP_PORT` | `993` |
| `IMAP_USERNAME` | `library@coulomb.social` |
| `IMAP_TLS` | `implicit` |
| `IMAP_FOLDER` | `INBOX` |

`IMAP_PASSWORD` is deliberately absent until the founder adds it as version 2.
Keep the existing fields when saving that new version, for example with
`bao kv patch platform/workloads/inbound-library/imap IMAP_PASSWORD=-`, which
reads the value from stdin.

This is an attended founder command. It needs the existing local OpenBao
forwarding:

```sh
BAO_ADDR=http://127.0.0.1:18200 VAULT_ADDR=http://127.0.0.1:18200 warden access openbao-platform-admin-login --exec -- python3 /home/worsch/railiance-platform/scripts/inbound_library_imap_entry.py
```

Behavior:
- The helper prints nothing.
- It writes with CAS=0, so it never overwrites any existing path or version.
- If a version already exists, it returns without reading values or writing.
- A successful rerun on an existing path proves only that the path exists, not
  what it contains.

Four tests cover:
- first creation;
- an existing version is kept;
- permission errors;
- CAS conflict.

Exit codes:

| Code | Meaning |
| --- | --- |
| 20 | invalid metadata |
| 21 | metadata access failure |
| 22 | creation failure |
| 23 | unexpected write version |
| 24 | verification failure |
| 25 | contained failure |

Read Warden's printed completion line:
- `login-failed`: no child process ran.
- `completed-but-revocation-unconfirmed`: creation ran, but the session
  revocation needs attention.

The native creation counts as pending until that attended result is in.

This helper does not do any of the following:
- grant read access to any workload;
- set a coding-agent deny boundary;
- copy another mailbox's credential;
- touch the mailbox.

inbound-library first runs on the workstation, with `INBOUND_LIBRARY_IMAP_USER`
and `INBOUND_LIBRARY_IMAP_PASSWORD` in its environment. Scoped delivery is a
separate, later step, done when the library moves into the cluster: a read
policy, an ESO ServiceAccount and an ExternalSecret, modelled on
`telemetry_smtp_delivery.py`. That later step also adds a certificate-verified,
read-only IMAP login check.