wsfed-caep 0.1.0__tar.gz

wsfed_caep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iya CyberSecurity Solutions, LLC
+
+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.

wsfed_caep-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: wsfed-caep
+Version: 0.1.0
+Summary: Server-side WS-Federation relying party that accepts SAML 2.0 assertions, and a CAEP and RISC receiver.
+Author: Iya CyberSecurity Solutions, LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rcbj/wsfed-caep-python
+Project-URL: Repository, https://github.com/rcbj/wsfed-caep-python
+Project-URL: Issues, https://github.com/rcbj/wsfed-caep-python/issues
+Keywords: ws-federation,wsfed,saml2,caep,risc,shared-signals
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Requires-Dist: lxml>=5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+<!--
+SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+SPDX-License-Identifier: MIT
+-->
+
+# wsfed-caep
+
+Server-side WS-Federation relying party for Python. It accepts SAML 2.0 bearer assertions, reads identity-provider federation metadata, writes relying-party metadata, verifies XML signatures, decrypts encrypted assertions, and remembers assertion ids so a bearer token cannot be replayed. A Shared Signals poll receiver for CAEP and RISC is included. The relying party does not start that receiver.
+
+Version 0.1.0. License: MIT. A pull request merged into `main` publishes the package to PyPI after the test workflow succeeds on that commit. A direct push does not. There is no API token: PyPI Trusted Publishing trades the workflow's GitHub OIDC token for a short-lived upload token, from the `pypi` environment, and PyPI holds the publisher for this repository and `publish.yml`. A version already on PyPI stays there; the next release is a new `version` in `pyproject.toml` (and `VERSION`). `develop` and `main` are the same commit when this tree is published; nothing here creates a remote.
+
+## Usage
+
+```python
+from wsfed_caep import RelyingParty
+
+rp = RelyingParty.from_file("wsfed.json")
+request = rp.login(relay_state="/")
+who = rp.handle_reply({"method": "POST", "url": "/wsfed", "body": body}, request.id)
+```
+
+JSON keys match the Node configuration: `realm`, `replyUrl`, `idpMetadata`, `privateKey`, `certificate`, `idpCa`, `idpEntityId`, `clockSkewSeconds`, `wantAssertionsEncrypted`, `allowUnsolicited`, `requestTokenType`, `signals`, `ssf`. `file:` and `env:` prefixes are accepted. The default subject attribute is `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier`.
+
+`signals` omitted or `true` is on. The resolved configuration omits the key in that case. `false` is kept, does not start a receiver, and does not require transmitter metadata. Sign-in is unchanged either way: WS-Federation does not send OAuth scopes. Any other value raises a config error whose message is `signals must be true or false`.
+
+```sh
+docker compose build
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  wsfed-caep-python-demo \
+  wsfed-caep generate-keys --config demo/wsfed.json
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  wsfed-caep-python-demo \
+  wsfed-caep metadata --config demo/wsfed.json
+```
+
+The generated certificate's common name defaults to `wsfed-caep-nodejs relying party` plus the realm, cut at 64 characters.
+
+## Tests
+
+```bash
+docker build --target test .
+```
+
+The suite runs in a container.
+
+The suite includes a stub identity provider. Those tests do not start iya-sts.
+
+`python3 scripts/live_iya_sts.py` is the live half. It uses iya-sts (the latest main branch, in memory mode with persistence and clustering off, when `IYA_STS_URL` is unset; `IYA_STS_IMAGE` starts a fresh container from an image), copies this checkout to a scratch build context, builds the demo image, runs the install script inside it (which registers the demo, generates the key pair and writes the `idpCa` chain), then builds the demo image again so it carries the chain, checks the image holds the chain and no key, starts the demo with no CA mount, signs in through `GET /login`, and requires a credential-change event and a session-revoked event on `GET /live-status`. The second event ends the local session. It uses the host's Python and Docker and does not import this library. It uses two high ports (defaults 18556 and 18656, `LIVE_STS_PORT` and `LIVE_DEMO_PORT`) and never binds 3000, 8081 or 18481-18495. No secret appears on a docker command line, and sign-in requests are logged by fixed labels, not URLs. The nightly workflow (06:35 UTC) runs the unit suite and this script once every 24 hours.
+
+## Layout
+
+- `src/wsfed_caep/` library
+- `tests/` pytest, fixtures, stub identity provider
+- `demo/app.py` stdlib HTTP demo
+- `scripts/configure_iya_sts.py` registers the demo with iya-sts and writes the listener CA trust chain to the file `idpCa` names
+- `scripts/trust_chain.py` holds `save_trust_chain()` and refreshes that file
+- `scripts/live_iya_sts.py` live sign-in against iya-sts
+- `.github/workflows/nightly.yml` unit suite and live script, once every 24 hours
+- `Dockerfile`, `docker-compose.yml` (`network_mode: host`, `PORT=3000`)
+
+## The iya-sts trust chain (`idpCa`)
+
+`idpCa` in `demo/wsfed.json` names the iya-sts TLS listener CA trust chain the library trusts for the IdP metadata URL and the Shared Signals transmitter. The default is `file:generated/idp-ca.pem`, relative to `demo/`. The value may also be a plain path, `env:<NAME>`, or the PEM itself. The library loads every certificate in it as a trust anchor (`ssl` `load_verify_locations(cadata=...)`), so the whole chain works and OpenSSL ends the path at the self-signed Root. The presented leaf must still verify to one of those anchors (a forged leaf followed by the real CA certificates is refused), and the host name is checked against the leaf's subject alternative names (a DNS name, or an IP literal such as `127.0.0.1`).
+
+`scripts/configure_iya_sts.py`, the install script, writes that file on every run (`scripts/trust_chain.py`, `save_trust_chain()`). It saves the whole chain iya-sts publishes at `GET /tls/server-certificate` (leaf, TLS Issuing CA, Intermediate, Root), or the chain from the TLS handshake when that path does not answer. It prints the path, the trust anchor's subject and its SHA-256 fingerprint. Compare the anchor with the Root CA on iya-sts's PKI page. A password iya-sts generates for the test user is never printed: it goes to `demo/generated/<user>.password`, mode 0600.
+
+The demo image build copies that file into the image at `/app/demo/generated/idp-ca.pem`, so the image trusts that iya-sts with no bind mount and no fetch. Run the install script before you build the image, and rebuild the image after running the install script against a different iya-sts. `.dockerignore` admits only that file from `demo/generated`: the relying party's key, certificate and the IdP metadata stay out of the image (compose still mounts `demo/generated` read-only for them). A build with no chain file yet (a fresh clone, CI) still succeeds; the image then has no `idpCa` file.
+
+The mechanism is `COPY demo ./demo` plus `.dockerignore`'s `demo/generated/*` and `!demo/generated/idp-ca.pem`. Do not replace it with a COPY that names the file or globs for it: when the file is absent, both BuildKit and the classic builder fail. A directory COPY of `demo/` (which always exists) succeeds in both. `python scripts/trust_chain.py --config demo/wsfed.json --idp <iya-sts URL>` refreshes the file by hand.
+
+## Demo
+
+`PORT` defaults to 3000. A loopback realm and reply URL follow that port. Any other host stays as written. `PUBLIC_URL` or `--public-url` replaces the origin and keeps the path. The default `http://localhost:3000` is not an explicit public URL. `GET /healthz` returns `200` and the body `ok` even when generated keys are absent. `GET /login` redirects to the identity provider with `wa=wsignin1.0`, `wtrealm`, `wreply`, and `wctx`. The reply URL accepts the sign-in POST and `wsignoutcleanup1.0`. `POST /logout` signs out, including at the identity provider. `GET /live-status` is JSON: `signedIn`, `subject`, the receiver state, and the Shared Signals events this process has accepted (`type` and `jti` only). No token is in that body.
+
+Demo JSON uses `file:` paths under `demo/generated/`. Those keys are not in the tree. `"signals"` is omitted, so the receiver is on when a transmitter is configured.
+
+```sh
+PORT=40123 docker compose up --build
+```

wsfed_caep-0.1.0/README.md

@@ -0,0 +1,81 @@
+<!--
+SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+SPDX-License-Identifier: MIT
+-->
+
+# wsfed-caep
+
+Server-side WS-Federation relying party for Python. It accepts SAML 2.0 bearer assertions, reads identity-provider federation metadata, writes relying-party metadata, verifies XML signatures, decrypts encrypted assertions, and remembers assertion ids so a bearer token cannot be replayed. A Shared Signals poll receiver for CAEP and RISC is included. The relying party does not start that receiver.
+
+Version 0.1.0. License: MIT. A pull request merged into `main` publishes the package to PyPI after the test workflow succeeds on that commit. A direct push does not. There is no API token: PyPI Trusted Publishing trades the workflow's GitHub OIDC token for a short-lived upload token, from the `pypi` environment, and PyPI holds the publisher for this repository and `publish.yml`. A version already on PyPI stays there; the next release is a new `version` in `pyproject.toml` (and `VERSION`). `develop` and `main` are the same commit when this tree is published; nothing here creates a remote.
+
+## Usage
+
+```python
+from wsfed_caep import RelyingParty
+
+rp = RelyingParty.from_file("wsfed.json")
+request = rp.login(relay_state="/")
+who = rp.handle_reply({"method": "POST", "url": "/wsfed", "body": body}, request.id)
+```
+
+JSON keys match the Node configuration: `realm`, `replyUrl`, `idpMetadata`, `privateKey`, `certificate`, `idpCa`, `idpEntityId`, `clockSkewSeconds`, `wantAssertionsEncrypted`, `allowUnsolicited`, `requestTokenType`, `signals`, `ssf`. `file:` and `env:` prefixes are accepted. The default subject attribute is `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier`.
+
+`signals` omitted or `true` is on. The resolved configuration omits the key in that case. `false` is kept, does not start a receiver, and does not require transmitter metadata. Sign-in is unchanged either way: WS-Federation does not send OAuth scopes. Any other value raises a config error whose message is `signals must be true or false`.
+
+```sh
+docker compose build
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  wsfed-caep-python-demo \
+  wsfed-caep generate-keys --config demo/wsfed.json
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  wsfed-caep-python-demo \
+  wsfed-caep metadata --config demo/wsfed.json
+```
+
+The generated certificate's common name defaults to `wsfed-caep-nodejs relying party` plus the realm, cut at 64 characters.
+
+## Tests
+
+```bash
+docker build --target test .
+```
+
+The suite runs in a container.
+
+The suite includes a stub identity provider. Those tests do not start iya-sts.
+
+`python3 scripts/live_iya_sts.py` is the live half. It uses iya-sts (the latest main branch, in memory mode with persistence and clustering off, when `IYA_STS_URL` is unset; `IYA_STS_IMAGE` starts a fresh container from an image), copies this checkout to a scratch build context, builds the demo image, runs the install script inside it (which registers the demo, generates the key pair and writes the `idpCa` chain), then builds the demo image again so it carries the chain, checks the image holds the chain and no key, starts the demo with no CA mount, signs in through `GET /login`, and requires a credential-change event and a session-revoked event on `GET /live-status`. The second event ends the local session. It uses the host's Python and Docker and does not import this library. It uses two high ports (defaults 18556 and 18656, `LIVE_STS_PORT` and `LIVE_DEMO_PORT`) and never binds 3000, 8081 or 18481-18495. No secret appears on a docker command line, and sign-in requests are logged by fixed labels, not URLs. The nightly workflow (06:35 UTC) runs the unit suite and this script once every 24 hours.
+
+## Layout
+
+- `src/wsfed_caep/` library
+- `tests/` pytest, fixtures, stub identity provider
+- `demo/app.py` stdlib HTTP demo
+- `scripts/configure_iya_sts.py` registers the demo with iya-sts and writes the listener CA trust chain to the file `idpCa` names
+- `scripts/trust_chain.py` holds `save_trust_chain()` and refreshes that file
+- `scripts/live_iya_sts.py` live sign-in against iya-sts
+- `.github/workflows/nightly.yml` unit suite and live script, once every 24 hours
+- `Dockerfile`, `docker-compose.yml` (`network_mode: host`, `PORT=3000`)
+
+## The iya-sts trust chain (`idpCa`)
+
+`idpCa` in `demo/wsfed.json` names the iya-sts TLS listener CA trust chain the library trusts for the IdP metadata URL and the Shared Signals transmitter. The default is `file:generated/idp-ca.pem`, relative to `demo/`. The value may also be a plain path, `env:<NAME>`, or the PEM itself. The library loads every certificate in it as a trust anchor (`ssl` `load_verify_locations(cadata=...)`), so the whole chain works and OpenSSL ends the path at the self-signed Root. The presented leaf must still verify to one of those anchors (a forged leaf followed by the real CA certificates is refused), and the host name is checked against the leaf's subject alternative names (a DNS name, or an IP literal such as `127.0.0.1`).
+
+`scripts/configure_iya_sts.py`, the install script, writes that file on every run (`scripts/trust_chain.py`, `save_trust_chain()`). It saves the whole chain iya-sts publishes at `GET /tls/server-certificate` (leaf, TLS Issuing CA, Intermediate, Root), or the chain from the TLS handshake when that path does not answer. It prints the path, the trust anchor's subject and its SHA-256 fingerprint. Compare the anchor with the Root CA on iya-sts's PKI page. A password iya-sts generates for the test user is never printed: it goes to `demo/generated/<user>.password`, mode 0600.
+
+The demo image build copies that file into the image at `/app/demo/generated/idp-ca.pem`, so the image trusts that iya-sts with no bind mount and no fetch. Run the install script before you build the image, and rebuild the image after running the install script against a different iya-sts. `.dockerignore` admits only that file from `demo/generated`: the relying party's key, certificate and the IdP metadata stay out of the image (compose still mounts `demo/generated` read-only for them). A build with no chain file yet (a fresh clone, CI) still succeeds; the image then has no `idpCa` file.
+
+The mechanism is `COPY demo ./demo` plus `.dockerignore`'s `demo/generated/*` and `!demo/generated/idp-ca.pem`. Do not replace it with a COPY that names the file or globs for it: when the file is absent, both BuildKit and the classic builder fail. A directory COPY of `demo/` (which always exists) succeeds in both. `python scripts/trust_chain.py --config demo/wsfed.json --idp <iya-sts URL>` refreshes the file by hand.
+
+## Demo
+
+`PORT` defaults to 3000. A loopback realm and reply URL follow that port. Any other host stays as written. `PUBLIC_URL` or `--public-url` replaces the origin and keeps the path. The default `http://localhost:3000` is not an explicit public URL. `GET /healthz` returns `200` and the body `ok` even when generated keys are absent. `GET /login` redirects to the identity provider with `wa=wsignin1.0`, `wtrealm`, `wreply`, and `wctx`. The reply URL accepts the sign-in POST and `wsignoutcleanup1.0`. `POST /logout` signs out, including at the identity provider. `GET /live-status` is JSON: `signedIn`, `subject`, the receiver state, and the Shared Signals events this process has accepted (`type` and `jti` only). No token is in that body.
+
+Demo JSON uses `file:` paths under `demo/generated/`. Those keys are not in the tree. `"signals"` is omitted, so the receiver is on when a transmitter is configured.
+
+```sh
+PORT=40123 docker compose up --build
+```

wsfed_caep-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wsfed-caep"
+version = "0.1.0"
+description = "Server-side WS-Federation relying party that accepts SAML 2.0 assertions, and a CAEP and RISC receiver."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Iya CyberSecurity Solutions, LLC" }]
+keywords = ["ws-federation", "wsfed", "saml2", "caep", "risc", "shared-signals"]
+dependencies = [
+  "cryptography>=42",
+  "lxml>=5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+wsfed-caep = "wsfed_caep.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src", "tests"]
+
+[project.urls]
+Homepage = "https://github.com/rcbj/wsfed-caep-python"
+Repository = "https://github.com/rcbj/wsfed-caep-python"
+Issues = "https://github.com/rcbj/wsfed-caep-python/issues"

wsfed_caep-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wsfed_caep-0.1.0/src/wsfed_caep/__init__.py

@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""Server-side WS-Federation relying party that accepts SAML 2.0 assertions, and a CAEP and RISC receiver.
+
+``signals: false`` turns the receiver off. The relying party does not start one itself. The default is
+on. Sign-in does not change, because WS-Federation does not send OAuth scopes. The flag only gates the
+receiver and the requirement for transmitter metadata.
+
+    from wsfed_caep import RelyingParty
+
+    rp = RelyingParty.from_file("wsfed.json")
+    request = rp.login(relay_state="/")
+    who = rp.handle_reply({"method": method, "url": url, "body": body}, request_id)
+"""
+
+from wsfed_caep.config import read_config_file, resolve_config
+from wsfed_caep.errors import WsFedError
+from wsfed_caep.metadata import IdpMetadata
+from wsfed_caep.relying_party import RelyingParty
+from wsfed_caep.replay import MemoryReplayCache
+from wsfed_caep.ssf import (
+    CAEP_EVENTS,
+    DEFAULT_ENDING_EVENTS,
+    DEFAULT_EVENTS_REQUESTED,
+    EVENT,
+    RISC_EVENTS,
+    MemorySessionIndex,
+    SignalsReceiver,
+    subject_of,
+    tracked_from,
+)
+from wsfed_caep.ssf.session_index import DEFAULT_SUBJECT_ATTRIBUTE
+from wsfed_caep.token import WsFedLogin
+from wsfed_caep.x509util import KeyPair, create_self_signed_key_pair
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CAEP_EVENTS",
+    "DEFAULT_ENDING_EVENTS",
+    "DEFAULT_EVENTS_REQUESTED",
+    "DEFAULT_SUBJECT_ATTRIBUTE",
+    "EVENT",
+    "IdpMetadata",
+    "KeyPair",
+    "MemoryReplayCache",
+    "MemorySessionIndex",
+    "RISC_EVENTS",
+    "RelyingParty",
+    "SignalsReceiver",
+    "WsFedError",
+    "WsFedLogin",
+    "create_self_signed_key_pair",
+    "read_config_file",
+    "resolve_config",
+    "subject_of",
+    "tracked_from",
+]

wsfed_caep-0.1.0/src/wsfed_caep/cli.py

@@ -0,0 +1,149 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""wsfed-caep command line: generate-keys and metadata."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from wsfed_caep.config import resolve_config
+from wsfed_caep.relying_party import RelyingParty
+from wsfed_caep.x509util import create_self_signed_key_pair
+
+USAGE = """Usage:
+  wsfed-caep generate-keys --config <wsfed.json> [--cn <name>] [--days <n>] [--bits <n>] [--force]
+  wsfed-caep generate-keys --key <file> --cert <file> [--cn <name>] [--days <n>] [--bits <n>] [--force]
+      A new RSA key and a self-signed certificate, written where the configuration's privateKey and
+      certificate point (or to --key and --cert). Refuses to replace existing files without --force.
+      The key decrypts encrypted assertions and can authenticate the Shared Signals receiver (mutual
+      TLS); WS-Federation itself signs nothing. The common name defaults to one naming the realm.
+
+  wsfed-caep metadata --config <wsfed.json> [--out <file>]
+      This relying party's federation metadata, from the configuration (and its certificate, when it
+      has one): give it to the identity provider. Written to --out, or to standard output."""
+
+
+def parse_args(argv: list[str]) -> tuple[str | None, dict]:
+    if not argv:
+        return None, {}
+    command, rest = argv[0], argv[1:]
+    args: dict = {}
+    i = 0
+    while i < len(rest):
+        item = rest[i]
+        if not item.startswith("--"):
+            raise SystemExit(f"unexpected argument {item}\n\n{USAGE}")
+        key = item[2:]
+        if key in ("force", "help"):
+            args[key] = True
+        else:
+            if i + 1 >= len(rest) or rest[i + 1].startswith("--"):
+                raise SystemExit(f"--{key} needs a value\n\n{USAGE}")
+            args[key] = rest[i + 1]
+            i += 1
+        i += 1
+    return command, args
+
+
+def _strip_file(value: str) -> str:
+    return value[5:] if value.startswith("file:") else value
+
+
+def key_paths(args: dict) -> tuple[str, str, str]:
+    config_path = args.get("config") if isinstance(args.get("config"), str) else None
+    key = args.get("key") if isinstance(args.get("key"), str) else None
+    cert = args.get("cert") if isinstance(args.get("cert"), str) else None
+    common_name = args.get("cn") if isinstance(args.get("cn"), str) else None
+    if config_path:
+        raw = json.loads(Path(config_path).read_text(encoding="utf-8"))
+        base = Path(config_path).resolve().parent
+
+        def at(value, what):
+            if not value or "-----BEGIN " in value:
+                raise SystemExit(f"{config_path}'s {what} must be a file path for generate-keys to write to")
+            value = _strip_file(value)
+            path = Path(value)
+            return path if path.is_absolute() else base / path
+
+        if key is None and raw.get("privateKey"):
+            key = str(at(raw.get("privateKey"), "privateKey"))
+        if cert is None and raw.get("certificate"):
+            cert = str(at(raw.get("certificate"), "certificate"))
+        if not common_name and raw.get("realm"):
+            common_name = f"wsfed-caep-nodejs relying party {raw['realm']}"[:64]
+    if not key or not cert:
+        raise SystemExit(f"generate-keys needs --config, or --key and --cert\n\n{USAGE}")
+    return str(Path(key).resolve()), str(Path(cert).resolve()), common_name or "wsfed-caep-nodejs relying party"
+
+
+def main(argv: list[str] | None = None, out=None) -> None:
+    if argv is None:
+        argv = sys.argv[1:]
+    if out is None:
+        out = sys.stdout.write
+    command, args = parse_args(list(argv))
+    if not command or args.get("help") or command == "help":
+        out(USAGE + "\n")
+        return
+    if command == "generate-keys":
+        key, cert, common_name = key_paths(args)
+        if not args.get("force") and (os.path.exists(key) or os.path.exists(cert)):
+            which = key if os.path.exists(key) else cert
+            raise SystemExit(
+                f"{which} already exists; pass --force to replace the key pair.\n"
+                "Replacing it means giving the identity provider the new metadata before it next encrypts to this relying party."
+            )
+        days = int(args["days"]) if isinstance(args.get("days"), str) else None
+        bits = int(args["bits"]) if isinstance(args.get("bits"), str) else None
+        if days is not None and days <= 0:
+            raise SystemExit("--days must be a positive whole number")
+        if bits is not None and bits not in (2048, 3072, 4096):
+            raise SystemExit("--bits must be 2048, 3072 or 4096")
+        pair = create_self_signed_key_pair(common_name, days=days or 1095, bits=bits or 3072)
+        Path(key).parent.mkdir(parents=True, exist_ok=True)
+        Path(cert).parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(key, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, pair.private_key_pem.encode())
+        finally:
+            os.close(fd)
+        Path(cert).write_text(pair.certificate_pem, encoding="utf-8")
+        os.chmod(cert, 0o644)
+        out(f"Wrote the private key  {key} (mode 600)\n")
+        out(f"Wrote the certificate  {cert}\n")
+        out(f"  subject   {pair.certificate.subject.rfc4514_string()}\n")
+        return
+    if command == "metadata":
+        config_path = args.get("config") if isinstance(args.get("config"), str) else None
+        if not config_path:
+            raise SystemExit(f"metadata needs --config\n\n{USAGE}")
+        raw = json.loads(Path(config_path).read_text(encoding="utf-8"))
+        raw.pop("idpCa", None)
+        xml = RelyingParty(resolve_config(raw, str(Path(config_path).resolve().parent)), None).metadata()
+        target = args.get("out") if isinstance(args.get("out"), str) else None
+        if target:
+            path = Path(target).resolve()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(xml, encoding="utf-8")
+            out(f"Wrote the relying party metadata to {path}\n")
+        else:
+            out(xml)
+        return
+    raise SystemExit(f"unknown command {command}\n\n{USAGE}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit as err:
+        if err.code not in (None, 0):
+            sys.stderr.write(f"{err.code if isinstance(err.code, str) else err}\n" if False else (f"{err.code}\n" if isinstance(err.code, str) else ""))
+            if isinstance(err.code, str):
+                sys.exit(1)
+        raise
+    except Exception as err:
+        sys.stderr.write(f"{err}\n")
+        sys.exit(1)

wsfed_caep-0.1.0/src/wsfed_caep/config.py

@@ -0,0 +1,153 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""Configuration. signals defaults to on. false is recorded; true and omitted are left off the result."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from urllib.parse import urlparse
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from wsfed_caep.errors import WsFedError
+
+
+class ResolvedConfig:
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+
+
+def _pem(value: str) -> bool:
+    return "-----BEGIN " in value
+
+
+def _material(value: str, base_dir: str, what: str) -> str:
+    if value.startswith("env:"):
+        name = value[4:]
+        if not os.environ.get(name):
+            raise WsFedError("config", f"{what} environment variable {name} is not set")
+        value = os.environ[name]
+    if value.startswith("file:"):
+        value = value[5:]
+    if _pem(value):
+        return value
+    path = value if os.path.isabs(value) else str(Path(base_dir) / value)
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except OSError as err:
+        raise WsFedError("config", f"{what} is neither a PEM nor a readable file ({path})", err) from err
+
+
+def _absolute_url(value, what: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise WsFedError("config", f"{what} is required")
+    try:
+        parsed = urlparse(value)
+        if parsed.scheme not in ("https", "http") or not parsed.netloc:
+            raise ValueError("not http(s)")
+    except Exception:
+        raise WsFedError("config", f"{what} must be an absolute http(s) URL, not {value}") from None
+    return value
+
+
+def _flag(value, default: bool, what: str) -> bool:
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        raise WsFedError("config", f"{what} must be true or false")
+    return value
+
+
+def _number(value) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _idp_metadata(value: str, base_dir: str) -> str:
+    value = value.strip()
+    if value.startswith("env:"):
+        name = value[4:]
+        if not os.environ.get(name):
+            raise WsFedError("config", f"idpMetadata environment variable {name} is not set")
+        value = os.environ[name].strip()
+    if value.startswith("file:"):
+        value = value[5:]
+    if value.startswith("http://") or value.startswith("https://") or value.startswith("<"):
+        return value
+    return value if os.path.isabs(value) else str(Path(base_dir) / value)
+
+
+def resolve_config(config: dict, base_dir: str | None = None) -> ResolvedConfig:
+    if not isinstance(config, dict):
+        raise WsFedError("config", "the configuration must be an object")
+    base = base_dir or os.getcwd()
+    realm = config.get("realm")
+    if not isinstance(realm, str) or not realm.strip():
+        raise WsFedError("config", "realm is required")
+    reply_url = _absolute_url(config.get("replyUrl"), "replyUrl")
+    raw_metadata = config.get("idpMetadata")
+    if not isinstance(raw_metadata, str) or not raw_metadata.strip():
+        raise WsFedError("config", "idpMetadata is required")
+    skew = 60 if config.get("clockSkewSeconds") is None else config.get("clockSkewSeconds")
+    if not _number(skew) or skew < 0 or skew > 600 or skew != skew:
+        raise WsFedError("config", "clockSkewSeconds must be a number from 0 to 600")
+    signals = _flag(config.get("signals") if "signals" in config else None, True, "signals")
+    # A missing key and an explicit JSON null are both the default. A non-boolean is an error.
+    if "signals" in config:
+        signals = _flag(config.get("signals"), True, "signals")
+    out = ResolvedConfig(
+        realm=realm,
+        reply_url=reply_url,
+        idp_metadata=_idp_metadata(raw_metadata, base),
+        clock_skew_ms=int(skew * 1000) if isinstance(skew, float) and not isinstance(skew, int) else int(skew) * 1000,
+        want_assertions_encrypted=_flag(config.get("wantAssertionsEncrypted") if "wantAssertionsEncrypted" in config else None, False, "wantAssertionsEncrypted"),
+        allow_unsolicited=_flag(config.get("allowUnsolicited") if "allowUnsolicited" in config else None, False, "allowUnsolicited"),
+        request_token_type=_flag(config.get("requestTokenType") if "requestTokenType" in config else None, True, "requestTokenType"),
+    )
+    if "wantAssertionsEncrypted" in config:
+        out.want_assertions_encrypted = _flag(config.get("wantAssertionsEncrypted"), False, "wantAssertionsEncrypted")
+    if "allowUnsolicited" in config:
+        out.allow_unsolicited = _flag(config.get("allowUnsolicited"), False, "allowUnsolicited")
+    if "requestTokenType" in config:
+        out.request_token_type = _flag(config.get("requestTokenType"), True, "requestTokenType")
+    if not signals:
+        out.signals = False
+    has_key = config.get("privateKey") is not None
+    has_cert = config.get("certificate") is not None
+    if has_key != has_cert:
+        raise WsFedError("config", "privateKey and certificate go together: give both or neither")
+    if has_key and has_cert:
+        try:
+            private_key = serialization.load_pem_private_key(_material(config["privateKey"], base, "privateKey").encode(), password=None)
+            certificate = x509.load_pem_x509_certificate(_material(config["certificate"], base, "certificate").encode())
+        except WsFedError:
+            raise
+        except Exception as err:
+            raise WsFedError("config", f"the private key or certificate cannot be read: {err}", err) from err
+        if not isinstance(private_key, rsa.RSAPrivateKey):
+            raise WsFedError("config", f"the private key is {type(private_key).__name__}; an RSA key is required")
+        if certificate.public_key().public_numbers() != private_key.public_key().public_numbers():
+            raise WsFedError("config", "the certificate is not for the private key")
+        out.private_key = private_key
+        out.certificate = certificate
+    elif out.want_assertions_encrypted:
+        raise WsFedError("config", "wantAssertionsEncrypted needs privateKey and certificate: the assertion is encrypted to them")
+    if config.get("idpCa"):
+        out.idp_ca = _material(config["idpCa"], base, "idpCa")
+    if config.get("idpEntityId"):
+        out.idp_entity_id = config["idpEntityId"]
+    return out
+
+
+def read_config_file(path: str, overrides: dict | None = None) -> ResolvedConfig:
+    overrides = overrides or {}
+    try:
+        parsed = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as err:
+        raise WsFedError("config", f"{path} cannot be read as JSON: {err}", err) from err
+    defined = {key: value for key, value in overrides.items() if value is not None}
+    merged = {**parsed, **defined}
+    return resolve_config(merged, str(Path(path).resolve().parent))