vortexpy 6.3.0__tar.gz → 6.4.0__tar.gz

{vortexpy-6.3.0 → vortexpy-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortexpy
-Version: 6.3.0
+Version: 6.4.0
 Summary: Flying Ion's observable, routable, data serialisation and transport code.
 Author-email: Flying Ion Pty Ltd <contact@flyingion.com>
 License: MIT

{vortexpy-6.3.0 → vortexpy-6.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortexpy"
-version = "6.3.0"
+version = "6.4.0"
 license = {text = "MIT"}
 authors = [{name = "Flying Ion Pty Ltd", email = "contact@flyingion.com"}]
 description = "Flying Ion's observable, routable, data serialisation and transport code."

{vortexpy-6.3.0 → vortexpy-6.4.0}/vortex/DeferUtil.py

@@ -16,6 +16,7 @@ import twisted
 from twisted.internet import reactor
 from twisted.internet.defer import (
     maybeDeferred,
+    CancelledError,
     Deferred,
     inlineCallbacks,
     ensureDeferred,
@@ -239,6 +240,17 @@ def deferToThreadWrapWithLogger(
                     )
 
             def handleFailure(failure):
+                if failure.check(CancelledError):
+                    # Cancellation is designed control flow (for example a
+                    # limitConcurrency timeout quarantining the thread), not
+                    # a threaded call failure.
+                    loggerArg.debug(
+                        "Threaded call cancelled in %s.%s",
+                        funcToWrap.__module__,
+                        funcToWrap.__qualname__,
+                    )
+                    return True if consumeError else failure
+
                 if logException:
                     return vortexLogFailure(
                         failure, loggerArg, consumeError=consumeError
@@ -253,6 +265,10 @@ def deferToThreadWrapWithLogger(
                 return True if consumeError else failure
 
             d: Deferred[_R] = deferToThread(timedFuncToRun, *args, **kwargs)
+            # Marks this Deferred as threaded for limitConcurrency: a timed
+            # out threaded call cannot be killed, so the limiter accumulates
+            # marked Deferreds in its quarantine registry.
+            d._isVortexThreadedCall = True  # type: ignore[attr-defined]
             d.addCallback(checkForInlineCallbackYield)
             d.addErrback(handleFailure)
             return d

{vortexpy-6.3.0 → vortexpy-6.4.0}/vortex/MtlsServerSslOptions.py

@@ -11,7 +11,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Optional
+from collections.abc import Callable
 
 from OpenSSL import SSL, crypto
 from twisted.internet._sslverify import Certificate, KeyPair, TLSVersion
@@ -31,9 +31,20 @@ class _MtlsServerCertificateOptions(CertificateOptions):
         self,
         *,
         authorized_client_registry: MtlsAuthorizedClientRegistry,
+        peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
         **kwargs,
     ) -> None:
+        """Constructor
+
+        :param authorized_client_registry: Mutable authorized client public
+            keys consulted by the verify callback.
+        :param peer_cert_acceptance_hook: Optional acceptance hook receiving
+            the peer leaf certificate PEM; consulted only when OpenSSL has
+            already validated the chain (``preverify_ok == 1``) and the
+            registry does not authorize the peer public key.
+        """
         self._authorizedClientRegistry = authorized_client_registry
+        self._peerCertAcceptanceHook = peer_cert_acceptance_hook
         super().__init__(**kwargs)
 
     def _makeContext(self):
@@ -57,47 +68,7 @@ class _MtlsServerCertificateOptions(CertificateOptions):
                 verify_flags |= SSL.VERIFY_CLIENT_ONCE
             self.trustRoot._addCACertsToContext(ctx)
 
-        registry = self._authorizedClientRegistry
-
-        def verifyCallback(
-            conn: SSL.Connection,
-            cert: crypto.X509,
-            errno: int,
-            depth: int,
-            preverify_ok: int,
-        ) -> int:
-            fail = 0
-
-            if depth != 0:
-                return preverify_ok
-
-            if preverify_ok == fail:
-                return preverify_ok
-
-            session_peer_public_key_bytes = crypto.dump_publickey(
-                crypto.FILETYPE_ASN1, cert.get_pubkey()
-            )
-            if not registry.isPublicKeyAuthorized(session_peer_public_key_bytes):
-                subject = cert.get_subject()
-                logger.error(
-                    "mTLS peer verify failed: certificate not authorized subject=%s",
-                    subject,
-                )
-                return fail
-
-            identity = registry.getIdentityForPublicKey(
-                session_peer_public_key_bytes
-            )
-            if identity is not None:
-                logger.info(
-                    "mTLS peer verified instanceId=%s owner=%s fingerprint=%s",
-                    identity.instanceId or "(unknown)",
-                    identity.ownerUsername or "(unknown)",
-                    identity.fingerprint,
-                )
-            return preverify_ok
-
-        ctx.set_verify(verify_flags, verifyCallback)
+        ctx.set_verify(verify_flags, self._verifyPeer)
         if self.verifyDepth is not None:
             ctx.set_verify_depth(self.verifyDepth)
 
@@ -124,14 +95,70 @@ class _MtlsServerCertificateOptions(CertificateOptions):
 
         return ctx
 
+    def _verifyPeer(
+        self,
+        conn: SSL.Connection,
+        cert: crypto.X509,
+        errno: int,
+        depth: int,
+        preverify_ok: int,
+    ) -> int:
+        """OpenSSL verify callback for the registry-backed mTLS allowlist.
+
+        OpenSSL validates the chain (signatures, validity, path length)
+        before this callback reports the leaf at depth 0. A
+        ``preverify_ok == 0`` leaf is returned unchanged so expiry and
+        path-length violations are never bypassed by the acceptance hook.
+        """
+        fail = 0
+
+        if depth != 0:
+            return preverify_ok
+
+        if preverify_ok == fail:
+            return preverify_ok
+
+        registry = self._authorizedClientRegistry
+        session_peer_public_key_bytes = crypto.dump_publickey(
+            crypto.FILETYPE_ASN1, cert.get_pubkey()
+        )
+        if not registry.isPublicKeyAuthorized(session_peer_public_key_bytes):
+            acceptanceHook = self._peerCertAcceptanceHook
+            if acceptanceHook is not None and acceptanceHook(
+                crypto.dump_certificate(crypto.FILETYPE_PEM, cert).decode("ascii")
+            ):
+                logger.info(
+                    "mTLS peer verified via peer certificate"
+                    " acceptance hook subject=%s",
+                    cert.get_subject(),
+                )
+                return preverify_ok
+            subject = cert.get_subject()
+            logger.error(
+                "mTLS peer verify failed: certificate not authorized subject=%s",
+                subject,
+            )
+            return fail
+
+        identity = registry.getIdentityForPublicKey(session_peer_public_key_bytes)
+        if identity is not None:
+            logger.info(
+                "mTLS peer verified instanceId=%s owner=%s fingerprint=%s",
+                identity.instanceId or "(unknown)",
+                identity.ownerUsername or "(unknown)",
+                identity.fingerprint,
+            )
+        return preverify_ok
+
 
 def buildMtlsServerCertificateOptions(
     private_key_with_full_chain: PrivateKeyWithFullChain,
     trust_root,
     authorized_client_registry: MtlsAuthorizedClientRegistry,
     *,
-    acceptable_protocols: Optional[list[bytes]] = None,
+    acceptable_protocols: list[bytes] | None = None,
     dh_parameters=None,
+    peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
 ) -> CertificateOptions:
     """Build server TLS options with dynamic authorized-client verification.
 
@@ -142,6 +169,11 @@ def buildMtlsServerCertificateOptions(
     :param private_key_with_full_chain: Server key + certificate chain PEM bank.
     :param trust_root: Twisted trust root for client certificate chain validation.
     :param authorized_client_registry: Mutable authorized client public keys.
+    :param peer_cert_acceptance_hook: Optional acceptance hook receiving the
+        peer leaf certificate PEM, consulted only when OpenSSL has validated
+        the chain and the registry does not authorize the peer public key;
+        it adds constraints OpenSSL cannot know (pinned-issuer membership,
+        certificate-name policy).
     :return: Twisted ``CertificateOptions`` for ``reactor.listenSSL``.
     """
     if acceptable_protocols is None:
@@ -165,6 +197,7 @@ def buildMtlsServerCertificateOptions(
 
     return _MtlsServerCertificateOptions(
         authorized_client_registry=authorized_client_registry,
+        peer_cert_acceptance_hook=peer_cert_acceptance_hook,
         privateKey=twisted_loaded_chain.privateKey,
         certificate=twisted_loaded_chain.certificate,
         extraCertChain=twisted_loaded_chain.intermediateCAs,

{vortexpy-6.3.0 → vortexpy-6.4.0}/vortex/VortexFactory.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import logging
 from collections import defaultdict, namedtuple
+from collections.abc import Callable
 from datetime import datetime
 
 import pytz
@@ -581,6 +582,7 @@ class VortexFactory:
         cls,
         name: str,
         mtlsAuthorizedClientRegistry: MtlsAuthorizedClientRegistry | None = None,
+        peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
     ) -> VortexWebSocketUpgradeResource:
         """Create Http Websocket Resource
 
@@ -588,6 +590,9 @@ class VortexFactory:
         :param mtlsAuthorizedClientRegistry: Authorized mTLS client
             certificate registry forwarded to the upgrade resource;
             ``None`` when the listener is not mTLS.
+        :param peer_cert_acceptance_hook: Optional acceptance hook
+            forwarded to the upgrade resource, consulted only when the
+            registry does not authorize the peer public key.
         :return: The configured :class:`VortexWebSocketUpgradeResource`.
         """
         vortexServer = VortexServer(name, requiresBase64Encoding=False)
@@ -599,6 +604,7 @@ class VortexFactory:
         return VortexWebSocketUpgradeResource(
             websocketFactory,
             mtlsAuthorizedClientRegistry=mtlsAuthorizedClientRegistry,
+            peer_cert_acceptance_hook=peer_cert_acceptance_hook,
         )
 
     @classmethod
@@ -607,6 +613,7 @@ class VortexFactory:
         name: str,
         rootResource,
         mtlsAuthorizedClientRegistry: MtlsAuthorizedClientRegistry | None = None,
+        peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
     ) -> None:
         """Create Server
 
@@ -620,6 +627,9 @@ class VortexFactory:
         :param mtlsAuthorizedClientRegistry: Authorized mTLS client
             certificate registry forwarded to the upgrade resource;
             ``None`` when the listener is not mTLS.
+        :param peer_cert_acceptance_hook: Optional acceptance hook
+            forwarded to the upgrade resource, consulted only when the
+            registry does not authorize the peer public key.
         :return: None
         """
 
@@ -631,6 +641,7 @@ class VortexFactory:
         websocketResource = VortexWebSocketUpgradeResource(
             websocketFactory,
             mtlsAuthorizedClientRegistry=mtlsAuthorizedClientRegistry,
+            peer_cert_acceptance_hook=peer_cert_acceptance_hook,
         )
         rootResource.putChild(b"vortexws", websocketResource)
 
@@ -640,6 +651,7 @@ class VortexFactory:
         name: str,
         port: int,
         mtlsAuthorizedClientRegistry: MtlsAuthorizedClientRegistry | None = None,
+        peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
     ) -> None:
         """Create Server
 
@@ -653,6 +665,9 @@ class VortexFactory:
         :param mtlsAuthorizedClientRegistry: Authorized mTLS client
             certificate registry forwarded to the TCP server factory;
             ``None`` when the listener is not mTLS.
+        :param peer_cert_acceptance_hook: Optional acceptance hook
+            forwarded to the TCP server factory, consulted only when the
+            registry does not authorize the peer public key.
         :return: None
         """
 
@@ -661,6 +676,7 @@ class VortexFactory:
         vortexTcpServerFactory = VortexTcpServerFactory(
             vortexServer,
             mtlsAuthorizedClientRegistry=mtlsAuthorizedClientRegistry,
+            peer_cert_acceptance_hook=peer_cert_acceptance_hook,
         )
         port = reactor.listenTCP(port, vortexTcpServerFactory)
         cls.__listeningPorts.append(port)

{vortexpy-6.3.0 → vortexpy-6.4.0}/vortex/VortexServerTcp.py

@@ -8,13 +8,18 @@
 
 from __future__ import annotations
 
+import hashlib
 import logging
+from collections.abc import Callable
 
 from OpenSSL import crypto
 from twisted.internet.defer import succeed
 from twisted.internet.protocol import Factory, connectionDone
 
-from vortex.MtlsAuthorizedClientRegistry import MtlsAuthorizedClientRegistry
+from vortex.MtlsAuthorizedClientRegistry import (
+    AuthorizedClientIdentity,
+    MtlsAuthorizedClientRegistry,
+)
 from vortex.VortexPayloadProtocol import VortexPayloadProtocol
 from vortex.VortexServerConnection import VortexServerConnection
 from vortex.VortexSession import (
@@ -36,6 +41,7 @@ class VortexTcpServerProtocol(VortexPayloadProtocol):
         vortex: VortexServer,
         addr,
         mtlsAuthorizedClientRegistry: MtlsAuthorizedClientRegistry | None = None,
+        peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
     ) -> None:
         """Constructor
 
@@ -44,11 +50,17 @@ class VortexTcpServerProtocol(VortexPayloadProtocol):
         :param mtlsAuthorizedClientRegistry: Authorized mTLS client
             certificate registry for this listener; ``None`` when the
             listener is not mTLS.
+        :param peer_cert_acceptance_hook: Optional acceptance hook
+            receiving the peer leaf certificate PEM, consulted only when
+            the registry does not authorize the peer public key; it adds
+            constraints OpenSSL cannot know (pinned-issuer membership,
+            certificate-name policy).
         """
         VortexPayloadProtocol.__init__(self, logger)
         self._vortex = vortex
         self._addr = addr
         self._mtlsAuthorizedClientRegistry = mtlsAuthorizedClientRegistry
+        self._peerCertAcceptanceHook = peer_cert_acceptance_hook
 
         self._conn = None
 
@@ -94,10 +106,14 @@ class VortexTcpServerProtocol(VortexPayloadProtocol):
         When an authorized-client registry is present and the TLS
         transport carries a peer certificate, the peer public key is
         resolved to its :class:`AuthorizedClientIdentity` and stored on
-        the session before :class:`PayloadIO` processes payloads. The
-        session attribute stays ``None`` when no registry is passed, the
-        listener is not mTLS, or the peer key is not authorized
-        (``MtlsServerSslOptions.verifyCallback`` already rejects
+        the session before :class:`PayloadIO` processes payloads. When
+        the registry does not hold the peer key, the peer certificate
+        acceptance hook decides identity resolution — an accepted peer
+        surfaces an identity derived from its certificate. The session
+        attribute stays ``None`` when no registry is passed, the
+        listener is not mTLS, or neither the registry nor the acceptance
+        hook authorizes the peer
+        (``_MtlsServerCertificateOptions._verifyPeer`` already rejects
         unauthorized keys during the TLS handshake).
         """
         if self._mtlsAuthorizedClientRegistry is None:
@@ -116,6 +132,10 @@ class VortexTcpServerProtocol(VortexPayloadProtocol):
         identity = self._mtlsAuthorizedClientRegistry.getIdentityForPublicKey(
             publicKeyAsn1
         )
+        if identity is None:
+            identity = self._resolveIdentityFromAcceptanceHook(
+                peerCertificate, publicKeyAsn1
+            )
         if identity is None:
             logger.warning(
                 "mTLS vortex TCP peer public key is not authorized;"
@@ -133,6 +153,57 @@ class VortexTcpServerProtocol(VortexPayloadProtocol):
         )
         vortexSession.mtlsClientIdentity = identity
 
+    def _resolveIdentityFromAcceptanceHook(
+        self,
+        peerCertificate: crypto.X509,
+        publicKeyAsn1: bytes,
+    ) -> AuthorizedClientIdentity | None:
+        """Resolve an identity for a peer the acceptance hook accepts.
+
+        The registry authorizes hub-issued certificates by public key;
+        peers the TLS acceptance hook accepted (for example
+        broker-issued leaves chaining to a pinned intermediate) surface
+        an identity derived from their certificate — the common name
+        identifies the peer and the fingerprint supports audit logs.
+
+        :param peerCertificate: The peer leaf certificate from the TLS
+            transport
+        :param publicKeyAsn1: The peer public key, DER encoded
+        :return: The derived identity, or ``None`` when no hook is
+            wired or the hook rejects the peer
+        """
+        acceptanceHook = self._peerCertAcceptanceHook
+        if acceptanceHook is None:
+            return None
+
+        certificatePem = crypto.dump_certificate(
+            crypto.FILETYPE_PEM, peerCertificate
+        ).decode("ascii")
+        if not acceptanceHook(certificatePem):
+            return None
+
+        fingerprint = hashlib.sha256(
+            crypto.dump_certificate(crypto.FILETYPE_ASN1, peerCertificate)
+        ).hexdigest()[:16]
+        subject = peerCertificate.get_subject()
+        commonName = (
+            subject.CN.decode("utf-8")
+            if isinstance(subject.CN, bytes)
+            else str(subject.CN or "")
+        )
+        logger.info(
+            "mTLS peer accepted via certificate acceptance hook cn=%s fingerprint=%s",
+            commonName,
+            fingerprint,
+        )
+        return AuthorizedClientIdentity(
+            fingerprint=fingerprint,
+            publicKeyAsn1=publicKeyAsn1,
+            instanceId=commonName,
+            ownerUsername="",
+            commonName=commonName,
+        )
+
     def _deliverPayload(self, payloadEnvelope):
         vs = (
             self._httpSession.getComponent(IVortexSession)
@@ -186,6 +257,7 @@ class VortexTcpServerFactory(Factory):
         self,
         vortexServer: VortexServer,
         mtlsAuthorizedClientRegistry: MtlsAuthorizedClientRegistry | None = None,
+        peer_cert_acceptance_hook: Callable[[str], bool] | None = None,
     ) -> None:
         """Constructor
 
@@ -194,9 +266,13 @@ class VortexTcpServerFactory(Factory):
         :param mtlsAuthorizedClientRegistry: Authorized mTLS client
             certificate registry for this listener; ``None`` when the
             listener is not mTLS.
+        :param peer_cert_acceptance_hook: Optional acceptance hook
+            forwarded to built protocols, consulted only when the
+            registry does not authorize the peer public key.
         """
         self._vortexServer = vortexServer
         self._mtlsAuthorizedClientRegistry = mtlsAuthorizedClientRegistry
+        self._peerCertAcceptanceHook = peer_cert_acceptance_hook
 
     def buildProtocol(self, addr):
         from vortex.VortexFactory import VortexFactory
@@ -208,6 +284,7 @@ class VortexTcpServerFactory(Factory):
             self._vortexServer,
             addr,
             mtlsAuthorizedClientRegistry=self._mtlsAuthorizedClientRegistry,
+            peer_cert_acceptance_hook=self._peerCertAcceptanceHook,
         )
         p.factory = self
         return p

{vortexpy-6.3.0 → vortexpy-6.4.0}/vortex/VortexServerTcp_test.py

@@ -10,6 +10,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from unittest.mock import MagicMock, patch
 
 from OpenSSL import crypto
@@ -36,6 +37,7 @@ def _makeSelfSignedCert(commonName: bytes = b"agent-instance-1") -> crypto.X509:
 def _makeProtocol(
     registry: MtlsAuthorizedClientRegistry | None,
     transport,
+    peerCertAcceptanceHook: Callable[[str], bool] | None = None,
 ) -> VortexTcpServerProtocol:
     vortex = MagicMock()
     vortex.uuid.return_value = "server-uuid"
@@ -44,6 +46,7 @@ def _makeProtocol(
         vortex,
         MagicMock(host="10.0.0.2"),
         mtlsAuthorizedClientRegistry=registry,
+        peer_cert_acceptance_hook=peerCertAcceptanceHook,
     )
     protocol.transport = transport
     return protocol
@@ -59,6 +62,20 @@ def test_factory_hands_registry_to_built_protocols() -> None:
     assert protocol._mtlsAuthorizedClientRegistry is registry
 
 
+def test_factory_hands_acceptance_hook_to_built_protocols() -> None:
+    def acceptingHook(leafCertPem: str) -> bool:
+        return True
+
+    factory = VortexTcpServerFactory(
+        MagicMock(), peer_cert_acceptance_hook=acceptingHook
+    )
+
+    with patch("vortex.VortexFactory.VortexFactory.canConnect", return_value=True):
+        protocol = factory.buildProtocol(MagicMock(host="10.0.0.2"))
+
+    assert protocol._peerCertAcceptanceHook is acceptingHook
+
+
 def test_factory_defaults_registry_to_none() -> None:
     factory = VortexTcpServerFactory(MagicMock())
 
@@ -119,3 +136,42 @@ def test_mtls_identity_none_for_unauthorized_peer_key() -> None:
 
     session = protocol._httpSession.getComponent(IVortexSession)
     assert session.mtlsClientIdentity is None
+
+
+def test_mtls_identity_resolved_for_hook_accepted_peer_cert() -> None:
+    registry = MtlsAuthorizedClientRegistry()
+    transport = MagicMock()
+    transport.getPeerCertificate.return_value = _makeSelfSignedCert(
+        b"user-mcp-operator@example.com"
+    )
+    protocol = _makeProtocol(registry, transport, lambda leafCertPem: True)
+
+    protocol._nameAndUuidReceived("remote-vortex", "remote-uuid")
+
+    session = protocol._httpSession.getComponent(IVortexSession)
+    assert session.mtlsClientIdentity is not None, (
+        "a hook-accepted peer must surface an identity on the session"
+    )
+    assert session.mtlsClientIdentity.commonName == "user-mcp-operator@example.com"
+    assert session.mtlsClientIdentity.instanceId == "user-mcp-operator@example.com", (
+        "the derived identity names the peer by its certificate common name"
+    )
+    assert len(session.mtlsClientIdentity.fingerprint) == 16, (
+        "the derived fingerprint mirrors the registry's sha256[:16] form"
+    )
+
+
+def test_mtls_identity_none_when_hook_rejects() -> None:
+    registry = MtlsAuthorizedClientRegistry()
+    transport = MagicMock()
+    transport.getPeerCertificate.return_value = _makeSelfSignedCert(
+        b"user-mcp-operator@example.com"
+    )
+    protocol = _makeProtocol(registry, transport, lambda leafCertPem: False)
+
+    protocol._nameAndUuidReceived("remote-vortex", "remote-uuid")
+
+    session = protocol._httpSession.getComponent(IVortexSession)
+    assert session.mtlsClientIdentity is None, (
+        "a hook-rejected peer must carry no client identity"
+    )