Metadata-Version: 2.4
Name: senora
Version: 0.4.0
Summary: Python client library for the DaMe (Datennetz der Medizin) S/MIME mail exchange used by Austrian healthcare providers
Project-URL: Homepage, https://nerdocs.at/
Project-URL: Source, https://github.com/nerdocs/senora
Author-email: Christian Gonzalez <christian@nerdocs.at>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: amipas,austria,cms,dame,healthcare,s/mime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.13
Requires-Dist: asn1crypto>=1.5
Requires-Dist: cryptography>=42
Requires-Dist: ldap3>=2.9
Provides-Extra: cli
Requires-Dist: pydifact-aek; extra == 'cli'
Provides-Extra: test
Requires-Dist: aiosmtpd>=1.4; extra == 'test'
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# señora

Python client library for **DaMe** — the *Datennetz der Medizin* S/MIME-based
messaging network used by Austrian healthcare providers (operated by Telekom
Austria / VTG, historically *Gesundheitsnetz Vorarlberg*).

This library replaces the legacy Java `DaMe.jar` client with a pure-Python
implementation that can be embedded in e.g. Django or used standalone.

## What this library does

- Fetch S/MIME-encrypted mails from a DaMe POP3 mailbox, verify signatures,
  decrypt content, and expose attachments as plain bytes.
- Sign and encrypt outgoing documents with your PKCS#12 identity, look up
  recipient certificates in the `esignature.telekom.at` LDAP directory, and
  submit them via the DaMe SMTP relay.
- Generate and process S/MIME Message Disposition Notifications (MDN, RFC 8098).
- Apply the DaMe filename policy (prefix-based sequence numbers).

## What it deliberately does not do

- **EDIFACT parsing** — use [pydifact](https://pypi.org/project/pydifact/) and
  `pydifact-aek` for Austrian laboratory findings.
- **DICOM send/receive** — a separate tier, use
  [pynetdicom](https://pypi.org/project/pynetdicom/).
- **GUI** — this is a library.

## Install

```sh
uv pip install senora
```

For local development:

```sh
uv venv
uv pip install -e '.[test]'
uv run pytest
```

## Quick start

```python
from pathlib import Path
from senora import Client, Identity, PeerLookup

identity = Identity.from_pkcs12(
    Path("certs/mykey.p12").read_bytes(),
    password="MEXXXXXX",
)

client = Client(
    identity=identity,
    pop3_host="mail.dame.at",
    pop3_port=995,            # POP3S (implicit TLS); default
    pop3_tls="ssl",           # default
    pop3_user="mexxxxxx@dame.at",
    pop3_password="...",
    smtp_host="dsmtp.dame.at",
    smtp_port=587,
    smtp_user="mexxxxxx@dame.at",
    smtp_password="...",
    peer_lookup=PeerLookup(server="ldap://esignature.telekom.at"),
)

# Receive
for msg in client.fetch(delete=False):
    for att in msg.attachments:
        Path("inbox", att.filename).write_bytes(att.content)

# Send
client.send(
    recipient_hv="ME654321",
    attachments=[("befund.edi", edi_bytes, "application/edifact")],
    cipher="AES",
    sign=True,
    request_mdn=True,
)
```

## Security model

- **Private keys**: loaded from PKCS#12 into memory only; never written to disk.
  Store P12 passphrases in an OS keyring, Vault, systemd-credentials, or an
  equivalent secret manager — never in source or config files.
- **TLS**: POP3 fetch uses implicit TLS on port 995 by default
  (`mail.dame.at:995`, TLS 1.3, valid cert). SMTP submission uses STARTTLS
  on port 587. Legacy deployments without POP3S can opt back into plain
  port 110 by passing `pop3_port=110, pop3_tls="none"` — a cleartext
  warning will be logged on every connect.
- **CRL checking**: optional, enabled via `PeerLookup(check_crl=True)`.
- **Padding**: S/MIME content encryption uses PKCS#7 padding; RSA key transport
  uses PKCS#1 v1.5 for compatibility with legacy DaMe peers.

## Status

Alpha. Core primitives (S/MIME sign/verify/encrypt/decrypt, PKCS#12 loading,
POP3/SMTP transport, LDAP peer lookup, filename policy) are implemented and
unit-tested. Interop tests against the live `mail.dame.at` service are pending
(see `docs/TODO.md`).
