railiance-platform/docs/inbound-library-imap-custody.md

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:

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.