messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/redaction.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""PHI redaction for the exception/logging path (WP-6c; ASVS 16.2.5, PHI.md P1-3).
+
+Inbound HL7 is attacker-/PHI-bearing, and a Router/Handler is user code that can do
+``raise ValueError(f"bad value in {raw}")`` — which would otherwise carry the full message body into
+the stored ``last_error``/``message_events.detail`` and any log line built from it. :func:`safe_exc`
+is the **chokepoint**: every exception rendered into a stored disposition or a log is routed through
+it, so HL7-structured content is scrubbed while the exception **type** (the useful, non-PHI part) is
+kept.
+
+This is a conservative *redaction* of HL7-shaped content — **not** de-identification (that is a
+separate, centralized framework; see PHI.md §9). It errs toward over-redaction; the residual control
+for free-text PHI a user script invents (e.g. a bare ``"DOE^JANE"``) remains the "never put PHI in an
+exception message" convention. Pure stdlib (``re`` only), so it can be used from any engine package.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["redact", "safe_exc", "safe_text"]
+
+_REDACTED = "[redacted]"
+#: Max characters of a (redacted) exception message to keep — a raw HL7 body is long, so bound what
+#: reaches a stored ``last_error`` or a log line even after redaction.
+_DEFAULT_LIMIT = 200
+
+#: An HL7 **segment** span: a 3-char segment ID (``MSH``/``PID``/``OBX``/…) immediately followed by the
+#: field separator and field data to end-of-line. Catches a raw message (or fragment) embedded in an
+#: exception — the realistic vector. The segment ID is kept (not PHI, useful); the field data is cut.
+_HL7_SEGMENT = re.compile(r"\b([A-Z][A-Z0-9]{2})\|[^\r\n]*")
+#: A run carrying **≥2 HL7 delimiters** (``| ^ ~ &``) — a field/component dump like ``100^^^H^MR`` or
+#: ``DOE^JANE^M`` that may be PHI even without a segment header. The non-delimiter runs use **possessive**
+#: quantifiers (``*+``, Python 3.11+): the char classes are disjoint from the delimiters, so possessive
+#: matching can't change *what* matches, but it makes the scan **linear** — a long delimiter-free run
+#: (e.g. ``"a"*5000`` in a hostile exception string) can't trigger quadratic backtracking.
+_HL7_FIELD_RUN = re.compile(r"[^\s|^~&]*+[|^~&][^\s|^~&]*+(?:[|^~&][^\s|^~&]*+)+")
+
+
+def redact(text: str) -> str:
+    """Scrub HL7 segment/field content (potential PHI) from free text, keeping segment IDs. Conservative
+    (errs toward over-redaction); the goal is that a raw HL7 body embedded in an exception message can't
+    reach a log or the stored ``last_error``/``detail``. NOT de-identification (PHI.md §9)."""
+    if not text:
+        return text
+    scrubbed = _HL7_SEGMENT.sub(lambda m: f"{m.group(1)}|{_REDACTED}", text)
+    return _HL7_FIELD_RUN.sub(_REDACTED, scrubbed)
+
+
+def safe_text(text: str, *, limit: int = _DEFAULT_LIMIT) -> str:
+    """A PHI-redacted, length-bounded rendering of a free-text diagnostic string — the string analog of
+    :func:`safe_exc`, for error/detail text that isn't an exception object (joined strict-validation
+    errors, a ``last_error`` built at the store layer, a connector's reply-parse note). HL7-shaped content
+    is scrubbed (:func:`redact`) and the result truncated. Idempotent on already-:func:`safe_text`'d
+    input (``redact`` is a fixed point once delimiter runs are gone), so it is safe to re-apply as a
+    store-layer chokepoint over values a caller may already have scrubbed."""
+    message = redact(text).strip()
+    if len(message) > limit:
+        message = f"{message[:limit]}…(+{len(message) - limit} chars)"
+    return message
+
+
+def safe_exc(exc: BaseException, *, limit: int = _DEFAULT_LIMIT) -> str:
+    """A PHI-redacted, length-bounded rendering of ``exc`` for a stored ``last_error``/``detail`` or a
+    log line. Always keeps the exception **type** (safe + most useful); the message is redacted
+    (:func:`redact`) and truncated — so a Router/Handler that did ``raise ValueError(f"...{raw}")``
+    can't leak the HL7 body into the store or logs."""
+    name = type(exc).__name__
+    message = safe_text(str(exc), limit=limit)
+    return f"{name}: {message}" if message else name

messagefoundry/scaffold.py

@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Scaffold a standalone **config repo** for the ``messagefoundry init`` command.
+
+A deploying organization keeps its *configuration* (Connections/Routers/Handlers, code sets, and
+per-environment values) in its **own** repo, with the engine as a **read-only, version-pinned
+dependency** it never edits (ADR 0017). This module lays down that repo's skeleton: a runnable starter
+feed, ``environments/<env>.toml`` value stubs, a synthetic fixture, an instance ``messagefoundry.toml``,
+a pinned ``requirements.txt``, a CI ``check`` workflow, ``.vscode`` settings the extension reads, and a
+README — everything an analyst needs to author + validate + deploy config without touching engine source.
+
+The templates are plain strings (they ship in the wheel as part of this module — no package-data
+config). ``scaffold()`` writes them and never overwrites an existing file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from messagefoundry import __version__
+
+# A runnable starter feed: receive ADT over MLLP, archive admit/register/update events to a file. Uses
+# literals (not env()) so `messagefoundry check` is green on the first commit; the docstring shows the
+# env() upgrade. The router/handler defs carry `# type: ignore[no-untyped-def]` (the engine calls them
+# with a Message; user config isn't type-checked against that signature).
+_STARTER_FEED = '''\
+"""Starter feed — receive ADT over MLLP, archive admit/register/update events to a file.
+
+Replace this with your own Connections, Routers, and Handlers. The authoring surface is the top-level
+``messagefoundry`` package (inbound / outbound / @router / @handler / Send / Message / MLLP / File /
+env / code_set / current_environment / ...). See docs/CONNECTIONS.md in the engine.
+
+Connection names follow ``[TYPE]_[PARTNER]_[MESSAGE]``: ``IB_EXAMPLE_ADT`` is an inbound MLLP listener;
+``FILE-OUT_EXAMPLE_ADT`` is an outbound file writer.
+
+Per-environment values: replace a literal like ``port=2575`` with ``port=env("example_adt_port")`` and
+add ``example_adt_port = 2575`` to ``environments/<env>.toml`` (those value files resolve against the
+project root — launch ``serve`` from the repo root, or pin it via ``serve --project-root`` /
+``[environments].base_dir``; see the README). Secrets come from ``MEFOR_VALUE_<KEY>`` env vars, never
+the value files.
+"""
+
+from messagefoundry import File, MLLP, Send, handler, inbound, outbound, router
+
+inbound("IB_EXAMPLE_ADT", MLLP(port=2575), router="example_adt_router")
+outbound("FILE-OUT_EXAMPLE_ADT", File(directory="./out/example", filename="{MSH-10}.hl7"))
+
+
+@router("example_adt_router")
+def route(msg):  # type: ignore[no-untyped-def]
+    # The router sees EVERY received message and returns the handler(s) to run ([] = UNROUTED).
+    if msg["MSH-9.1"] != "ADT":
+        return []
+    return ["example_adt_archive"]
+
+
+@handler("example_adt_archive")
+def archive(msg):  # type: ignore[no-untyped-def]
+    # Filter -> (transform) -> Send. Only admit/register/update events are archived; others FILTERED.
+    if msg["MSH-9.2"] not in ("A01", "A04", "A08"):
+        return None
+    return Send("FILE-OUT_EXAMPLE_ADT", msg)
+'''
+
+# A synthetic ADT^A01 (NO real PHI) that routes + archives, so `check`'s dryrun delivers one message.
+# HL7 segments are CR-separated.
+_FIXTURE_ADT = (
+    "MSH|^~\\&|EXAMPLE|FAC|DEST|DEST|20260101120000||ADT^A01|MSG00001|P|2.5.1\r"
+    "EVN|A01|20260101120000\r"
+    "PID|1||100^^^HOSP^MR||DOE^JANE||19800101|F\r"
+    "PV1|1|I|WARD^101^A\r"
+)
+
+_ENV_DEV = """\
+# DEV environment values — resolved by env("key") in your config graph (see the engine's
+# docs/CONFIGURATION.md). NON-SECRET values only, versioned here so they're diffable/reviewable.
+# Secrets come from MEFOR_VALUE_<KEY> environment variables, never this file. Keys are lower_snake_case.
+#
+# Selected by [ai].environment = "dev" (or `serve --env dev`). The starter feed uses none; add keys as
+# you switch literals to env(), e.g.:
+# example_adt_port = 2575
+"""
+
+_ENV_PROD = """\
+# PROD environment values — same shape as dev.toml, with this instance's real (non-secret) endpoints.
+# Secrets come from MEFOR_VALUE_<KEY> environment variables, never this file.
+#
+# Selected by [ai].environment = "prod" (or `serve --env prod`).
+# example_adt_port = 2575
+"""
+
+# Service settings for ONE instance. Copy per deployed instance (Test/Prod/...) and set its environment
+# + posture + store + egress. Precedence: CLI > MEFOR_<SECTION>_<KEY> env > this file > default.
+_SERVICE_TOML = """\
+# MessageFoundry service settings for THIS instance. Keep one per deployed instance (dev/test/prod/...).
+# Precedence: CLI flag > MEFOR_<SECTION>_<KEY> env > this file > built-in default. Secrets go in env
+# (MEFOR_*), never here. See the engine's docs/CONFIGURATION.md.
+
+[store]
+# path = "messagefoundry.db"   # SQLite (default). Use a server DB for Test/Prod — see docs/DEPLOY-SERVER-DB.md.
+
+[api]
+host = "127.0.0.1"             # loopback only; an off-loopback bind requires TLS — see docs/DEPLOYMENT.md.
+port = 8765
+
+[ai]
+# The active-environment NAME — REQUIRED (also passable as `serve --env <name>`). Free-form: name
+# instances dev/staging/test/prod/poc/... Built-in names dev/staging/prod carry a default posture; a
+# CUSTOM name MUST also set data_class + production below (posture is never inferred from the name).
+environment = "dev"
+# Security posture, decoupled from the name (ADR 0017). Derived for dev/staging/prod when omitted:
+#   data_class = "phi"    # synthetic | phi — does this instance carry REAL PHI? (drives at-rest + egress advisories)
+#   production = true     # production tier? (drives the prod-DEBUG refusal + the AI data-scope ceiling)
+
+[environments]
+# Where environments/<env>.toml value files resolve FROM. Default (unset) = the process working
+# directory, so `serve` must be launched from the repo root. Set base_dir to this repo's ABSOLUTE root
+# — or pass `serve --project-root <repo>` — so values resolve no matter the launch CWD (REQUIRED under a
+# service like NSSM, where the working directory isn't the repo root). See docs/CONFIGURATION.md.
+# base_dir = "C:/srv/mefor/this-config-repo"
+
+[egress]
+# Lock down outbound destinations on any PHI-carrying instance (recommended for Test/Prod):
+# deny_by_default = true
+# allowed_mllp = ["receiver.test.example:2601"]
+"""
+
+_VSCODE_SETTINGS = """\
+{
+  "messagefoundry.configDir": "config",
+  "messagefoundry.messageSetsDir": "messages/sets"
+}
+"""
+
+# CI gate: verify the pinned engine wheel's build provenance, then install it and run `messagefoundry
+# check` (validate + dryrun + advisory lint) on every PR. `pip install -r requirements.txt` resolves the
+# engine from your configured index — public PyPI (the published releases carry SLSA + PEP 740
+# attestations), the engine's GitHub Release wheel, or a private index.
+_CI_WORKFLOW = """\
+name: check
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  # Supply-chain gate (MessageFoundry WP-BL3-07): verify the pinned engine wheel's SLSA build provenance
+  # BEFORE installing it, so a registry/mirror substitution of the engine fails the build instead of
+  # shipping silently. Fail-closed by default. If your package index strips attestations (some private
+  # mirrors do), set the repository variable MEFOR_VERIFY_ENGINE=off to skip this job (see README).
+  verify-engine:
+    runs-on: ubuntu-latest
+    if: ${{ vars.MEFOR_VERIFY_ENGINE != 'off' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Download the pinned engine wheel (no install)
+        run: |
+          pip download -r requirements.txt --no-deps --only-binary=:all: -d dist-verify
+      - name: Verify SLSA build provenance before install
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh attestation verify dist-verify/messagefoundry-*.whl --repo wshallwshall/MessageFoundry
+
+  check:
+    needs: verify-engine
+    # Run when verify passed OR was intentionally skipped (MEFOR_VERIFY_ENGINE=off); never when it failed
+    # — a failed/cancelled verify-engine fails the gate (fail-closed). `always()` lets this evaluate even
+    # though the dependency may have been skipped.
+    if: ${{ always() && needs.verify-engine.result != 'failure' && needs.verify-engine.result != 'cancelled' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the pinned MessageFoundry engine
+        run: pip install -r requirements.txt
+      # `check` runs validate + dryrun (the real gate). --no-lint skips the advisory ruff/mypy pass
+      # (those tools aren't in requirements.txt); add them and drop --no-lint to lint your config too.
+      - name: Validate config (validate + dryrun)
+        run: messagefoundry check --config config --messages messages/sets --no-lint
+"""
+
+_GITIGNORE = """\
+# MessageFoundry config repo — never commit local stores, secrets, captures, or build cruft.
+*.db
+*.db-shm
+*.db-wal
+*.log
+.env
+.env.*
+/out/
+captures/
+__pycache__/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.DS_Store
+Thumbs.db
+"""
+
+_GITATTRIBUTES = "# Keep the generated pre-commit hook LF so its shebang works on Windows.\n.mefor-hooks/** text eol=lf\n"
+
+_README = """\
+# MessageFoundry configuration
+
+This repository is a **MessageFoundry config repo**: it holds *your* integration configuration
+(Connections, Routers, Handlers, code sets, and per-environment values) and drives one or more engine
+instances (e.g. Test, Production). The **engine is a read-only, version-pinned dependency** — you never
+edit it here; you author config against its public surface (ADR 0017).
+
+## Layout
+- `config/` — the `--config` directory: your Connection/Router/Handler modules (and `codesets/`).
+- `environments/<env>.toml` — NON-secret per-environment values for `env("key")` lookups (versioned).
+  Secrets come from `MEFOR_VALUE_<KEY>` environment variables, never these files.
+- `messages/sets/` — synthetic HL7 fixtures that gate `messagefoundry check` (no real PHI).
+- `messagefoundry.toml` — this instance's service settings (active environment + posture, store, API, egress).
+- `requirements.txt` — pins the engine version this config targets.
+- `.github/workflows/check.yml` — CI: install the pinned engine + run `messagefoundry check` on every PR.
+
+## Use it
+```bash
+# 1. Install the pinned engine into a venv (the engine is a read-only dependency):
+python -m venv .venv && . .venv/bin/activate          # Windows: .\\.venv\\Scripts\\Activate.ps1
+pip install -r requirements.txt
+
+# 2. Validate your config (also runs in CI on every PR):
+messagefoundry check --config config --messages messages/sets
+
+# 3. Run an instance. environments/<env>.toml resolves against the project root — by default the
+#    process working directory, so launch from the repo root:
+messagefoundry serve --config config --env dev
+#    Or pin the root explicitly (an ABSOLUTE path) so it resolves no matter the launch directory —
+#    REQUIRED under a service like NSSM, where the CWD isn't the repo root:
+# messagefoundry serve --config config --env dev --project-root /srv/mefor/this-config-repo
+#    (Equivalently, set [environments].base_dir to that absolute path in messagefoundry.toml.)
+```
+
+> The engine version in `requirements.txt` is resolved from your configured package index — **PyPI**
+> (`pip install messagefoundry==<version>`; the published releases carry SLSA + PEP 740 attestations),
+> the engine's **GitHub Release wheel**, or a **private index**.
+
+## Engine integrity (supply-chain gate)
+`.github/workflows/check.yml` **verifies the pinned engine wheel's build provenance before installing it**
+(`gh attestation verify` against the MessageFoundry release attestation), so a registry/mirror swap of the
+engine fails CI instead of shipping silently — pinning a version proves *which bytes*, not *who built
+them*. The gate is **fail-closed by default**. If your package index strips attestations (some private
+mirrors do), set the repository variable **`MEFOR_VERIFY_ENGINE=off`** (Settings → Secrets and variables →
+Actions → Variables) to skip it; the `check` job still runs. See the engine's INSTALL-GUIDE for the
+matching manual verify-before-install recipe.
+
+## Environments & posture
+The active environment is **required** and **free-form** — name instances `dev`/`staging`/`test`/`prod`/`poc`/…
+Built-in names `dev`/`staging`/`prod` carry a default security posture; a **custom** name must set
+`[ai].data_class` (`synthetic`|`phi`) and `[ai].production` in `messagefoundry.toml`. One reviewed config
+commit is deployed to every instance; each instance picks its environment at runtime (`--env` or
+`[ai].environment`), so a Test instance never resolves Prod values.
+
+The selected `environments/<env>.toml` resolves against the **project root**: by default the process
+working directory (launch from the repo root), or pin it with `serve --project-root <abs-path>` /
+`[environments].base_dir` so it resolves regardless of the launch directory — required under a service
+(e.g. NSSM) where the working directory isn't the repo root.
+
+## Secrets
+Never commit secrets. Per-environment endpoints (non-secret) live in `environments/<env>.toml`; secrets
+(passwords, keys, WS-Security credentials) are injected per instance via `MEFOR_VALUE_*` (graph) and
+`MEFOR_*` (service) environment variables.
+
+---
+Generated by `messagefoundry init`.
+"""
+
+
+def _templates(version: str) -> dict[str, str]:
+    """The relative-path -> file-content map for a fresh config repo, pinning ``version``."""
+    return {
+        "README.md": _README,
+        "requirements.txt": f"messagefoundry=={version}\n",
+        ".gitignore": _GITIGNORE,
+        ".gitattributes": _GITATTRIBUTES,
+        ".vscode/settings.json": _VSCODE_SETTINGS,
+        ".github/workflows/check.yml": _CI_WORKFLOW,
+        "messagefoundry.toml": _SERVICE_TOML,
+        "config/IB_EXAMPLE_ADT.py": _STARTER_FEED,
+        "environments/dev.toml": _ENV_DEV,
+        "environments/prod.toml": _ENV_PROD,
+        "messages/sets/example_adt.hl7": _FIXTURE_ADT,
+    }
+
+
+def scaffold(target: str | Path, *, force: bool = False, version: str = __version__) -> list[Path]:
+    """Write a starter config-repo skeleton into ``target``; return the files written (sorted).
+
+    Refuses a **non-empty** ``target`` unless ``force`` is set. An existing file is **never**
+    overwritten (even with ``force``) — ``force`` only permits scaffolding the missing files into a
+    directory that already has content. ``version`` pins the engine in ``requirements.txt`` (defaults
+    to the running engine's version).
+    """
+    root = Path(target)
+    if root.exists() and root.is_dir() and any(root.iterdir()) and not force:
+        raise FileExistsError(
+            f"{root} is not empty — pass force=True to scaffold the missing files into it "
+            "(existing files are left untouched)"
+        )
+    if root.exists() and not root.is_dir():
+        raise NotADirectoryError(f"{root} exists and is not a directory")
+
+    written: list[Path] = []
+    for rel, content in _templates(version).items():
+        path = root / rel
+        if path.exists():
+            continue  # never clobber an existing file
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # newline="" writes the content verbatim — LF for text, the CR-separated HL7 fixture intact.
+        path.write_text(content, encoding="utf-8", newline="")
+        written.append(path)
+    return sorted(written)

messagefoundry/secrets_dpapi.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Windows DPAPI secret-at-rest helper (WP-11d; ASVS 13.3.1/13.3.2).
+
+The store encryption key is normally supplied as base64 via ``MEFOR_STORE_ENCRYPTION_KEY`` (the
+cross-platform default). On Windows an operator may instead keep it in a **DPAPI-protected key file**
+(``[store].encryption_key_file``): ``CryptProtectData`` binds the ciphertext to this machine
+(``LOCAL_MACHINE`` scope), so a copied file is useless off the protecting host and the plaintext key
+never sits in the service's environment block (readable by any local admin). At startup the service
+account ``CryptUnprotectData``s the file back to the base64 key.
+
+DPAPI is **Windows-only**. Every entry point raises :class:`DpapiUnavailable` elsewhere so callers
+degrade gracefully to the env-var key — this module never imports anything Windows-specific at module
+load, so it imports cleanly on Linux/macOS (CI lint leg) too. The ``ctypes.windll`` calls live behind
+``sys.platform != "win32"`` guards; mypy treats the code after the guard as unreachable off Windows
+(mirrors :mod:`messagefoundry.console.service_control`), so it type-checks on the Linux CI leg.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from pathlib import Path
+
+# CryptProtectData flags. LOCAL_MACHINE: any principal on THIS machine can unprotect — required so the
+# low-privilege *service account* (not just the installing admin) can read the key. UI_FORBIDDEN: never
+# raise a prompt (the engine runs headless under a service).
+_CRYPTPROTECT_UI_FORBIDDEN = 0x01
+_CRYPTPROTECT_LOCAL_MACHINE = 0x04
+
+
+class DpapiUnavailable(RuntimeError):
+    """DPAPI was requested off Windows — there is no ``CryptProtectData`` to call."""
+
+
+class DpapiError(RuntimeError):
+    """A DPAPI operation (protect/unprotect or the backing file I/O) failed."""
+
+
+def dpapi_available() -> bool:
+    """Whether DPAPI can be used here (Windows only)."""
+    return sys.platform == "win32"
+
+
+class _DataBlob(ctypes.Structure):
+    """The Win32 ``DATA_BLOB`` (cbData + pbData) passed to/from the CryptProtectData API."""
+
+    _fields_ = (("cbData", ctypes.c_uint32), ("pbData", ctypes.POINTER(ctypes.c_char)))
+
+
+def _to_blob(data: bytes) -> tuple[_DataBlob, ctypes.Array[ctypes.c_char]]:
+    # Return the buffer alongside the blob so the caller keeps it referenced for the call's duration
+    # (the blob only borrows the pointer; if the buffer is GC'd mid-call the read is use-after-free).
+    buf = ctypes.create_string_buffer(data, len(data))
+    blob = _DataBlob(len(data), ctypes.cast(buf, ctypes.POINTER(ctypes.c_char)))
+    return blob, buf
+
+
+def dpapi_protect(secret: bytes, *, machine_scope: bool = True) -> bytes:
+    """DPAPI-encrypt ``secret``. ``machine_scope`` (default) ties it to the machine so the service
+    account can decrypt; False ties it to the current user only. Raises :class:`DpapiUnavailable`
+    off Windows, :class:`DpapiError` on a Win32 failure."""
+    if sys.platform != "win32":
+        raise DpapiUnavailable("DPAPI (CryptProtectData) is only available on Windows")
+    crypt32 = ctypes.WinDLL("crypt32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    in_blob, _keep = _to_blob(secret)
+    out_blob = _DataBlob()
+    flags = _CRYPTPROTECT_UI_FORBIDDEN | (_CRYPTPROTECT_LOCAL_MACHINE if machine_scope else 0)
+    ok = crypt32.CryptProtectData(
+        ctypes.byref(in_blob), None, None, None, None, flags, ctypes.byref(out_blob)
+    )
+    if not ok:
+        raise DpapiError(f"CryptProtectData failed (Win32 error {ctypes.get_last_error()})")
+    try:
+        return ctypes.string_at(out_blob.pbData, out_blob.cbData)
+    finally:
+        kernel32.LocalFree(out_blob.pbData)
+
+
+def dpapi_unprotect(blob: bytes) -> bytes:
+    """DPAPI-decrypt a ciphertext produced by :func:`dpapi_protect` (on this machine/account).
+    Raises :class:`DpapiUnavailable` off Windows, :class:`DpapiError` on a Win32 failure (wrong
+    machine/account, or a corrupt/foreign blob)."""
+    if sys.platform != "win32":
+        raise DpapiUnavailable("DPAPI (CryptUnprotectData) is only available on Windows")
+    crypt32 = ctypes.WinDLL("crypt32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    in_blob, _keep = _to_blob(blob)
+    out_blob = _DataBlob()
+    ok = crypt32.CryptUnprotectData(
+        ctypes.byref(in_blob),
+        None,
+        None,
+        None,
+        None,
+        _CRYPTPROTECT_UI_FORBIDDEN,
+        ctypes.byref(out_blob),
+    )
+    if not ok:
+        raise DpapiError(
+            f"CryptUnprotectData failed (Win32 error {ctypes.get_last_error()}); the key file must be "
+            "unprotected on the same machine that protected it"
+        )
+    try:
+        return ctypes.string_at(out_blob.pbData, out_blob.cbData)
+    finally:
+        kernel32.LocalFree(out_blob.pbData)
+
+
+def protect_key_to_file(key_b64: str, path: Path, *, machine_scope: bool = True) -> None:
+    """DPAPI-protect a base64 store key and write the ciphertext to ``path`` (raises on non-Windows
+    or a write failure). The caller should restrict the file's ACL afterwards (``_secure_file``)."""
+    blob = dpapi_protect(key_b64.strip().encode("ascii"), machine_scope=machine_scope)
+    try:
+        path.write_bytes(blob)
+    except OSError as exc:
+        raise DpapiError(f"cannot write protected key file {path}: {exc}") from exc
+
+
+def load_protected_key(path: str | Path) -> str:
+    """Read and DPAPI-decrypt a key file into its base64 store key. Raises :class:`DpapiUnavailable`
+    off Windows or :class:`DpapiError` if the file is missing/unreadable/not decryptable here."""
+    p = Path(path)
+    try:
+        blob = p.read_bytes()
+    except OSError as exc:
+        raise DpapiError(f"cannot read encryption_key_file {p}: {exc}") from exc
+    return dpapi_unprotect(blob).decode("ascii").strip()

messagefoundry/store/__init__.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Durable message store + queue (SQLite WAL, transactional inbox/outbox).
+
+The store *is* the queue: persisting an inbound message and its per-destination outbox
+rows in one transaction buys at-least-once delivery, retries, and replay without a
+separate broker. See :mod:`messagefoundry.store.store` and docs/ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.store.base import (
+    AdminStore,
+    AuditStore,
+    AuthStore,
+    QueueStore,
+    Row,
+    Store,
+    StoreLifecycle,
+    open_store,
+    sqlite_settings,
+)
+from messagefoundry.store.store import (
+    MessageStatus,
+    MessageStore,
+    OutboxItem,
+    OutboxStatus,
+    Stage,
+)
+
+__all__ = [
+    "AdminStore",
+    "AuditStore",
+    "AuthStore",
+    "MessageStatus",
+    "MessageStore",
+    "OutboxItem",
+    "OutboxStatus",
+    "QueueStore",
+    "Row",
+    "Stage",
+    "Store",
+    "StoreLifecycle",
+    "open_store",
+    "sqlite_settings",
+]

messagefoundry/store/audit_tee.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Off-box audit tee — the single PHI-redaction path shared by every store backend (sec-offbox-log).
+
+Each store backend (SQLite, Postgres, SQL Server) calls :func:`emit_audit_tee` immediately after a
+``record_audit`` row is durably committed, so a **PHI-safe metadata** copy of the audit record is
+shipped off-box via the ``messagefoundry.audit`` logger — which propagates to the root stdout +
+optional syslog/SIEM forwarder configured by :mod:`messagefoundry.logging_setup`. So the audit trail
+survives a host/DB compromise (ASVS 16.x).
+
+One helper means there is exactly **one** place the off-box PHI-redaction guarantee lives, identical
+across all three backends — not three copies that could drift.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from messagefoundry.redaction import safe_text
+
+__all__ = ["audit_logger", "emit_audit_tee"]
+
+log = logging.getLogger(__name__)
+
+# Pinned to INFO so audit evidence forwards regardless of the deployment's general log level: the
+# logging_setup root handlers are NOTSET, so a record's only level gate is this logger's own level.
+# It propagates to those root handlers, so no logging_setup change is needed to reach the forwarder.
+audit_logger = logging.getLogger("messagefoundry.audit")
+audit_logger.setLevel(logging.INFO)
+
+
+def emit_audit_tee(
+    *,
+    action: str,
+    actor: str | None,
+    channel_id: str | None,
+    detail: str | None,
+    ts: float,
+) -> None:
+    """Tee a just-persisted ``audit_log`` record off-box as PHI-safe metadata (sec-offbox-log, ASVS
+    16.x). Emits actor / action / channel / timestamp plus a **redacted** ``detail`` to the
+    ``messagefoundry.audit`` logger.
+
+    **Never emits a raw message body.** ``detail`` can embed raw HL7 fragments from an exception
+    message (it is a cipher column at rest for exactly that reason), so it is run through
+    :func:`~messagefoundry.redaction.safe_text` — which scrubs HL7-shaped spans and bounds length —
+    before it leaves the process. The handler-level ``RedactionFilter`` re-scrubs as a backstop, but
+    redacting here keeps the off-box guarantee independent of handler config and **identical across
+    every backend**.
+
+    Best-effort: a logging failure must never fail the audit write (already committed), so it is
+    caught and logged, not raised. Callers invoke this **after commit** and **outside any write
+    lock/transaction**, so a synchronous syslog send can't block the event loop under a lock."""
+    record = {
+        "event": "audit",
+        "ts": ts,
+        "action": action,
+        "actor": actor,
+        "channel_id": channel_id,
+        # PHI chokepoint: redact HL7-shaped content + bound length before it ships off-box.
+        "detail": safe_text(detail) if detail else None,
+    }
+    try:
+        audit_logger.info(json.dumps(record, ensure_ascii=False))
+    except Exception:  # noqa: BLE001 — the audit row is durable; the off-box tee is best-effort
+        log.warning("off-box audit tee failed for action=%s", action, exc_info=True)