Metadata-Version: 2.4
Name: delegate-connector-email
Version: 0.1.0
Summary: OSS email connector for the Terrene Delegate substrate (kailash.delegate).
Project-URL: Homepage, https://github.com/terrene-foundation/delegate-connectors
Project-URL: Changelog, https://github.com/terrene-foundation/delegate-connectors/blob/main/CHANGELOG.md
Author: Terrene Foundation
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: connector,delegate,email,imap,kailash,smtp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aioimaplib>=1.0
Requires-Dist: aiosmtplib>=3.0
Requires-Dist: cryptography>=42.0
Requires-Dist: kailash>=2.28.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: python-dotenv>=1.0; extra == 'test'
Description-Content-Type: text/markdown

<!--
Copyright 2026 Terrene Foundation
SPDX-License-Identifier: Apache-2.0
-->

# delegate-connector-email

The first OSS Python connector for the Terrene Delegate substrate. Implements the
shipped `kailash.delegate.Connector` ABC (kailash 2.26.2) for email:

- **`write`** — SMTP outbound send, executed under audit, returns a real
  `SignedActionEnvelope`.
- **`read`** — IMAP inbound fetch, executed under audit, returns
  `(messages, AttestedReadReceipt)`.
- **`authenticate`** — resolves a sender/recipient address to a `Principal`
  against a `PrincipalDirectory` (exact-match in v0; unknown sender → `Reject`,
  fail-closed).
- **`invoke`** — single-method dispatch entry (used by the dispatch hot path);
  dispatches a send and returns a `ConnectorInvocationResult`.
- Trust properties — `auth_verifier` returns the wired `Ed25519Verifier`;
  `ledger` / `revocation` return shipped concretes (framework-first; no custom
  trust primitives).

It subclasses `Connector` **directly** (ADR-1) — NOT `LegacyInvokeConnector`,
whose proxied `read`/`write` emit empty, unverifiable receipts. This connector's
`read`/`write` produce non-empty receipts that verify under a real
`Ed25519Verifier`.

## Install

```bash
pip install -e connectors/email
```

## Configure

All credentials come from the environment (see `.env.example`):
`EMAIL_SMTP_HOST/PORT/USER/PASSWORD/USE_TLS` and the `EMAIL_IMAP_*` equivalents.
Nothing is hardcoded; nothing is logged.

## Test

Tier-1 (unit, no I/O):

```bash
pip install -e "connectors/email[test]"
python -m pytest connectors/email/tests/unit -q
```

Tier-2/3 (real infra — Mailpit + GreenMail, no mocks at the boundary):

```bash
docker compose -f connectors/email/docker-compose.yml up -d
python -m pytest connectors/email/tests/integration -q
docker compose -f connectors/email/docker-compose.yml down
```

Two real mail servers back the tier: **Mailpit** (SMTP `:1025` + REST/UI `:8025`)
for the outbound send + arrival assertion, and **GreenMail** (`greenmail/standalone`;
real SMTP `:3025` + real IMAP `:3143`) for the inbound IMAP round-trip — Mailpit
v1.30.0 ships no IMAP server. If Docker is unavailable the integration tests skip
with a clear reason (they do not fake the boundary).

## Known limitation — runtime `execute()` audit gate

`compose.py` builds a real `DelegateRuntime` around the connector. However the
shipped `kailash.delegate` runtime/dispatch audit-emit path signs the event
payload bytes while `AuditChainEngine.emit_event` verifies the signature against
the full audit-entry signing bytes — so `runtime.execute()` fails at the first
audit emission under any real verifier. This is an SDK bug in `kailash.delegate`,
not in this connector; the connector's own `read`/`write` receipts verify
correctly. See `workspaces/email/journal/0005-GAP-*` for the full evidence and
reproduction. The end-to-end `runtime.execute()` assertion is gated on the SDK
fix; the connector-level SMTP→IMAP round-trip and receipt verification are not.

## License

Apache 2.0. All open-source IP is owned by the Terrene Foundation.
