painfree 0.1.0__tar.gz

painfree-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reyemb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

painfree-0.1.0/NOTICE

@@ -0,0 +1,49 @@
+painfree
+Copyright (c) 2026 reyemb
+
+This product is licensed under the MIT License. The full text is in LICENSE,
+and that notice covers everything in this distribution.
+
+--------------------------------------------------------------------------------
+Third-party notices
+--------------------------------------------------------------------------------
+
+ebics-api/ebics-client-php
+https://github.com/ebics-api/ebics-client-php
+
+The EBICS 3.0 protocol engine in `painfree/ebics3/` is a Python port of
+`ebics-api/ebics-client-php`. It is not a copy: the code was rewritten in
+Python against a different XML and cryptography stack, and it does not
+reproduce the PHP source. It does follow that project's structure and its
+solutions to the parts of EBICS the specification leaves ambiguous, which is
+enough that its licence travels with this distribution rather than being left
+behind in a commit message.
+
+`ebics-client-php` is MIT licensed. Its notice, reproduced in full:
+
+    MIT License
+
+    Copyright (c) 2019-2020 EBICS API
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+
+No other project's source was read or adapted into `painfree/ebics3/`. The
+Ruby `epics` and the Python `fintech` implementations are used only as
+black-box oracles: they are executed and their output is compared, and neither
+contributes code to this distribution.

painfree-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: painfree
+Version: 0.1.0
+Summary: Self-hosted middleware that accepts JSON payment instructions and submits them to banks over EBICS 3.0
+Project-URL: Homepage, https://github.com/reyemb/painfree-ebics-middleware-python
+Project-URL: Source, https://github.com/reyemb/painfree-ebics-middleware-python
+Project-URL: Issues, https://github.com/reyemb/painfree-ebics-middleware-python/issues
+Project-URL: Changelog, https://github.com/reyemb/painfree-ebics-middleware-python/releases
+Author-email: reyemb <m3y3r.bastian@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: banking,camt,ebics,iso20022,pain.001,payments,sepa
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: cryptography>=42
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jinja2>=3.1
+Requires-Dist: lxml>=5.2
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pyjwt==2.11.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# painfree
+
+**JSON in, EBICS out.** Self-hosted middleware that accepts authenticated HTTP
+requests and submits them to your banks over EBICS 3.0, so payment files stop
+being something a human uploads by hand.
+
+```
+your system  ──JSON/HTTPS──▶  painfree  ──EBICS 3.0 (H005)──▶  bank A
+                (OIDC)         │                                bank B
+                               │                                bank C
+                               └──webhook──▶  your system
+```
+
+POST a payment as JSON. painfree validates it, builds a compliant `pain.001`,
+signs and encrypts it per the EBICS protocol, uploads it to the right bank
+connection, tracks the order to acknowledgement, and calls your webhook when the
+status changes. It runs the other direction too: scheduled downloads of
+`camt.052/053/054` and `pain.002`, normalised to JSON.
+
+A console at `/ui` handles everything that is not a payment: bank connections,
+EBICS initialisation, key management, order history, replay, audit.
+
+## Status
+
+**Early.** Not in production. Not suitable for anyone else's money.
+
+## Run it
+
+Four lines, against the published image. Nothing is built.
+
+```bash
+cp deploy/production.env.example .env    # pinned to ghcr.io/reyemb/painfree
+deploy/init-secrets.sh                   # four secret files, generated once
+docker compose up -d                     # db, api, worker, TLS proxy
+docker compose exec api python -m painfree create-admin you    # no OIDC only
+```
+
+Open the address in `.env`. Set
+`PAINFREE_SITE_ADDRESS=https://painfree.localhost` to run it on a machine with
+no DNS: the proxy issues that certificate from its own local CA.
+`podman-compose` works identically, and `deploy/build-image.sh` builds the
+image yourself if you would rather not run someone else's.
+
+Everything that is not secret lives in `.env`. Every secret is a file under
+`deploy/secrets/`, generated once, mounted at runtime, and never baked into the
+image or committed.
+
+## Submitting a payment
+
+```bash
+curl -X POST https://painfree.localhost/v1/connections/acme-ubs/payments \
+     -u you:the-password-you-set \
+     -H 'Idempotency-Key: caller-idem-0001' \
+     -H 'Content-Type: application/json' -d @payment.json
+```
+
+`202 Accepted` with an `order_id` to poll at `/v1/orders/{order_id}`. Accepted
+means accepted **for processing**, not that the bank has it. The instruction is
+validated against the ISO 20022 schema *and* the Swiss Payment Standards rules
+before anything is signed, so a malformed QR reference comes back immediately
+naming the field, rather than from the bank two hours later.
+
+One idempotency key stays one order, and an order can end accepted at most once.
+
+**Payment schemes.** A payment carries `normal`, `instant`, or
+`instant_or_normal`, which tries instant and sends an ordinary transfer if the
+bank definitively refuses. A timeout, a dropped connection or an answer that
+will not parse is an unknown outcome rather than a refusal: the order is
+retried carrying the message it already had, so nothing is sent twice.
+
+`/ui/api` renders the request body, every endpoint and the privilege it demands,
+generated from the router rather than written down, and links the OpenAPI
+documents beside it.
+
+## How it works
+
+**Two processes, one image.** `api` serves HTTP and is refused the custody
+secret. `worker` holds it, and does every upload, download and key operation. An
+`api` process handed the secret does not start, and production refuses to run
+both halves in one process. That is a security boundary rather than a scaling
+one: the process answering requests has nothing to decrypt a private key with.
+
+**Authentication.** OIDC where you have a provider (browser SSO with PKCE, JWT
+bearer for machines), and HTTP Basic against local accounts where you do not.
+Production refuses to start in development mode. A process accepts one kind of
+credential and never two.
+
+**Authorisation.** Two roles: `admin`, which may grant access, and `member`,
+which may not. Everything a member holds is a grant naming a subject, a bank
+connection and a level. `viewer` reads; `operator` also submits payments,
+replays orders and manages schedules. Grants are read from the database on
+every request, so revoking somebody takes effect on their next request. A
+connection a caller holds no grant on answers `404`, exactly like one that was
+never registered.
+
+**Webhooks.** At-least-once. The event is written in the same transaction as
+the fact it reports, so a crash cannot lose it, and a redelivery carries the
+same `event_id`: deduplicate on that. Each request is signed
+`X-Painfree-Signature: v1=<hex>`, an HMAC-SHA256 over `"<timestamp>.<raw
+body>"` with the subscription's own secret. Verify over the bytes you received,
+not over a re-serialisation.
+
+**Keys.** INI, HIA and HPB from the console, with a printable INI letter,
+renewal and suspension. The bank's keys are trusted only once you have compared
+their fingerprints against the letter the bank sent, on a page where nothing is
+pre-filled and declining is as easy as accepting.
+
+## Configuration
+
+Every setting is an environment variable, and any of them can be read from a
+file instead by setting `PAINFREE_X_FILE`. The ones a deployment sets are in
+`deploy/production.env.example`; the rest are documented where they are
+defined, in `painfree/config.py`.
+
+| Variable | Default | What |
+|---|---|---|
+| `PAINFREE_ENVIRONMENT` | `development` | `production` refuses SQLite, `combined`, and development auth |
+| `PAINFREE_ROLE` | `combined` | `api`, `worker` or `combined` |
+| `PAINFREE_DATABASE_URL` | SQLite file | PostgreSQL in production |
+| `PAINFREE_KEY_ENCRYPTION_SECRET` | none | seals every stored private key; required of a worker, refused for an `api` |
+| `PAINFREE_AUTH_MODE` | derived | `oidc`, `basic`, or `development`, which production refuses |
+| `PAINFREE_TLS_TERMINATED_UPSTREAM` | `false` | `basic` in production will not start without it |
+| `PAINFREE_OIDC_ISSUER` / `_CLIENT_ID` / `_REDIRECT_URI` | none | all three required for `oidc` |
+
+Logs are one JSON object per line on stdout. No token, authorization code,
+session id or client secret ever reaches the stream.
+
+## Backup, and the one thing no backup covers
+
+`deploy/backup.sh` dumps the database and `deploy/restore.sh` restores it. That
+covers the sealed keys, the order history, the idempotency ledger and the audit
+trail.
+
+It does not cover `PAINFREE_KEY_ENCRYPTION_SECRET`, which is in no backup and
+which nothing recovers. Lose it and every sealed key is unreadable by anyone,
+and each bank connection has to be re-keyed on paper. Rotating it is `python -m
+painfree rekey`, run with both secrets present, which re-seals every row and
+fails loudly on any it could not move.
+
+## Develop
+
+```bash
+uv sync --extra dev
+uv run python -m painfree     # SQLite, migrated at startup, on :8000
+uv run pytest
+```
+
+Development mode authenticates from `X-Painfree-Dev-Principal` and
+`X-Painfree-Dev-Roles`, so a checkout runs and the suite passes with no provider
+to point at. It is still an authentication step, and production refuses to start
+in it.
+
+There is one importable package, `painfree`; the EBICS 3.0 engine is the
+subpackage `painfree/ebics3/`, which imports nothing from the service around it
+and needs only `lxml` and `cryptography`.
+
+## Licence
+
+**MIT.** Copyright (c) 2026 reyemb. The full text is in
+[LICENSE](https://github.com/reyemb/painfree-ebics-middleware-python/blob/main/LICENSE).
+
+The EBICS 3.0 engine in `painfree/ebics3/` is a Python port of
+[`ebics-api/ebics-client-php`](https://github.com/ebics-api/ebics-client-php),
+which is MIT too. Its notice is reproduced in full in
+[NOTICE](https://github.com/reyemb/painfree-ebics-middleware-python/blob/main/NOTICE),
+which every copy has to keep, and both files ship inside the wheel, the
+source distribution and the container image.

painfree-0.1.0/README.md

@@ -0,0 +1,167 @@
+# painfree
+
+**JSON in, EBICS out.** Self-hosted middleware that accepts authenticated HTTP
+requests and submits them to your banks over EBICS 3.0, so payment files stop
+being something a human uploads by hand.
+
+```
+your system  ──JSON/HTTPS──▶  painfree  ──EBICS 3.0 (H005)──▶  bank A
+                (OIDC)         │                                bank B
+                               │                                bank C
+                               └──webhook──▶  your system
+```
+
+POST a payment as JSON. painfree validates it, builds a compliant `pain.001`,
+signs and encrypts it per the EBICS protocol, uploads it to the right bank
+connection, tracks the order to acknowledgement, and calls your webhook when the
+status changes. It runs the other direction too: scheduled downloads of
+`camt.052/053/054` and `pain.002`, normalised to JSON.
+
+A console at `/ui` handles everything that is not a payment: bank connections,
+EBICS initialisation, key management, order history, replay, audit.
+
+## Status
+
+**Early.** Not in production. Not suitable for anyone else's money.
+
+## Run it
+
+Four lines, against the published image. Nothing is built.
+
+```bash
+cp deploy/production.env.example .env    # pinned to ghcr.io/reyemb/painfree
+deploy/init-secrets.sh                   # four secret files, generated once
+docker compose up -d                     # db, api, worker, TLS proxy
+docker compose exec api python -m painfree create-admin you    # no OIDC only
+```
+
+Open the address in `.env`. Set
+`PAINFREE_SITE_ADDRESS=https://painfree.localhost` to run it on a machine with
+no DNS: the proxy issues that certificate from its own local CA.
+`podman-compose` works identically, and `deploy/build-image.sh` builds the
+image yourself if you would rather not run someone else's.
+
+Everything that is not secret lives in `.env`. Every secret is a file under
+`deploy/secrets/`, generated once, mounted at runtime, and never baked into the
+image or committed.
+
+## Submitting a payment
+
+```bash
+curl -X POST https://painfree.localhost/v1/connections/acme-ubs/payments \
+     -u you:the-password-you-set \
+     -H 'Idempotency-Key: caller-idem-0001' \
+     -H 'Content-Type: application/json' -d @payment.json
+```
+
+`202 Accepted` with an `order_id` to poll at `/v1/orders/{order_id}`. Accepted
+means accepted **for processing**, not that the bank has it. The instruction is
+validated against the ISO 20022 schema *and* the Swiss Payment Standards rules
+before anything is signed, so a malformed QR reference comes back immediately
+naming the field, rather than from the bank two hours later.
+
+One idempotency key stays one order, and an order can end accepted at most once.
+
+**Payment schemes.** A payment carries `normal`, `instant`, or
+`instant_or_normal`, which tries instant and sends an ordinary transfer if the
+bank definitively refuses. A timeout, a dropped connection or an answer that
+will not parse is an unknown outcome rather than a refusal: the order is
+retried carrying the message it already had, so nothing is sent twice.
+
+`/ui/api` renders the request body, every endpoint and the privilege it demands,
+generated from the router rather than written down, and links the OpenAPI
+documents beside it.
+
+## How it works
+
+**Two processes, one image.** `api` serves HTTP and is refused the custody
+secret. `worker` holds it, and does every upload, download and key operation. An
+`api` process handed the secret does not start, and production refuses to run
+both halves in one process. That is a security boundary rather than a scaling
+one: the process answering requests has nothing to decrypt a private key with.
+
+**Authentication.** OIDC where you have a provider (browser SSO with PKCE, JWT
+bearer for machines), and HTTP Basic against local accounts where you do not.
+Production refuses to start in development mode. A process accepts one kind of
+credential and never two.
+
+**Authorisation.** Two roles: `admin`, which may grant access, and `member`,
+which may not. Everything a member holds is a grant naming a subject, a bank
+connection and a level. `viewer` reads; `operator` also submits payments,
+replays orders and manages schedules. Grants are read from the database on
+every request, so revoking somebody takes effect on their next request. A
+connection a caller holds no grant on answers `404`, exactly like one that was
+never registered.
+
+**Webhooks.** At-least-once. The event is written in the same transaction as
+the fact it reports, so a crash cannot lose it, and a redelivery carries the
+same `event_id`: deduplicate on that. Each request is signed
+`X-Painfree-Signature: v1=<hex>`, an HMAC-SHA256 over `"<timestamp>.<raw
+body>"` with the subscription's own secret. Verify over the bytes you received,
+not over a re-serialisation.
+
+**Keys.** INI, HIA and HPB from the console, with a printable INI letter,
+renewal and suspension. The bank's keys are trusted only once you have compared
+their fingerprints against the letter the bank sent, on a page where nothing is
+pre-filled and declining is as easy as accepting.
+
+## Configuration
+
+Every setting is an environment variable, and any of them can be read from a
+file instead by setting `PAINFREE_X_FILE`. The ones a deployment sets are in
+`deploy/production.env.example`; the rest are documented where they are
+defined, in `painfree/config.py`.
+
+| Variable | Default | What |
+|---|---|---|
+| `PAINFREE_ENVIRONMENT` | `development` | `production` refuses SQLite, `combined`, and development auth |
+| `PAINFREE_ROLE` | `combined` | `api`, `worker` or `combined` |
+| `PAINFREE_DATABASE_URL` | SQLite file | PostgreSQL in production |
+| `PAINFREE_KEY_ENCRYPTION_SECRET` | none | seals every stored private key; required of a worker, refused for an `api` |
+| `PAINFREE_AUTH_MODE` | derived | `oidc`, `basic`, or `development`, which production refuses |
+| `PAINFREE_TLS_TERMINATED_UPSTREAM` | `false` | `basic` in production will not start without it |
+| `PAINFREE_OIDC_ISSUER` / `_CLIENT_ID` / `_REDIRECT_URI` | none | all three required for `oidc` |
+
+Logs are one JSON object per line on stdout. No token, authorization code,
+session id or client secret ever reaches the stream.
+
+## Backup, and the one thing no backup covers
+
+`deploy/backup.sh` dumps the database and `deploy/restore.sh` restores it. That
+covers the sealed keys, the order history, the idempotency ledger and the audit
+trail.
+
+It does not cover `PAINFREE_KEY_ENCRYPTION_SECRET`, which is in no backup and
+which nothing recovers. Lose it and every sealed key is unreadable by anyone,
+and each bank connection has to be re-keyed on paper. Rotating it is `python -m
+painfree rekey`, run with both secrets present, which re-seals every row and
+fails loudly on any it could not move.
+
+## Develop
+
+```bash
+uv sync --extra dev
+uv run python -m painfree     # SQLite, migrated at startup, on :8000
+uv run pytest
+```
+
+Development mode authenticates from `X-Painfree-Dev-Principal` and
+`X-Painfree-Dev-Roles`, so a checkout runs and the suite passes with no provider
+to point at. It is still an authentication step, and production refuses to start
+in it.
+
+There is one importable package, `painfree`; the EBICS 3.0 engine is the
+subpackage `painfree/ebics3/`, which imports nothing from the service around it
+and needs only `lxml` and `cryptography`.
+
+## Licence
+
+**MIT.** Copyright (c) 2026 reyemb. The full text is in
+[LICENSE](https://github.com/reyemb/painfree-ebics-middleware-python/blob/main/LICENSE).
+
+The EBICS 3.0 engine in `painfree/ebics3/` is a Python port of
+[`ebics-api/ebics-client-php`](https://github.com/ebics-api/ebics-client-php),
+which is MIT too. Its notice is reproduced in full in
+[NOTICE](https://github.com/reyemb/painfree-ebics-middleware-python/blob/main/NOTICE),
+which every copy has to keep, and both files ship inside the wheel, the
+source distribution and the container image.

painfree-0.1.0/hatch_build.py

@@ -0,0 +1,32 @@
+"""Keep `.gitignore` out of the source distribution.
+
+The build backend force-includes every VCS exclusion file in an sdist, and a
+force-include is not subject to the target's `exclude` patterns, so this is the
+only place it can be dropped.
+
+It matters because `.gitignore` in this repository is not just build noise: it
+names the working paths that are deliberately kept local, and a source
+distribution published to an index is exactly where that list should not
+appear. The sdist is meant to be the source a rebuild needs, and a rebuild
+needs none of it.
+
+Scoped to the sdist target, so the wheel build -- which is what the container
+image runs, from a directory that holds only `pyproject.toml` and the package
+-- never has to find this file.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class GitignoreOutOfSdistHook(BuildHookInterface):
+    PLUGIN_NAME = "gitignore-out-of-sdist"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        forced = build_data.get("force_include", {})
+        for source in [p for p in forced if os.path.basename(p) == ".gitignore"]:
+            del forced[source]

painfree-0.1.0/painfree/__init__.py

@@ -0,0 +1,15 @@
+"""painfree -- JSON in, EBICS out.
+
+The service layer lives directly under this package; the EBICS 3.0 protocol
+engine is the subpackage :mod:`painfree.ebics3`, which must not import from any
+other part of ``painfree``. This module is deliberately empty apart from the
+version, so that importing the engine does not drag FastAPI, SQLAlchemy or a
+database driver in with it -- that is what keeps the engine releasable on its
+own.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]