authweave-core 7.0.0__tar.gz

authweave_core-7.0.0/.gitignore

@@ -0,0 +1,186 @@
+.gitignore### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+*.db
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# zensical documentation
+/site
+docs/_include/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+.env
+.uv-cache
+
+# AI agents
+PRD.md
+AGENTS.md
+CLAUDE.md
+TECHSTACK.md
+.agents/
+.claude/
+.cursor/
+.codacy/
+.codegraph/

authweave_core-7.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Shepilov
+
+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.

authweave_core-7.0.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: authweave-core
+Version: 7.0.0
+Summary: Framework-neutral principal authentication contracts and coordinator
+Project-URL: homepage, https://github.com/ZYLVEXT/litestar-auth
+Project-URL: documentation, https://zylvext.github.io/litestar-auth/
+Project-URL: source, https://github.com/ZYLVEXT/litestar-auth
+Project-URL: tracker, https://github.com/ZYLVEXT/litestar-auth/issues
+Author-email: Vladislav Shepilov <shepilov.v@protonmail.com>
+Maintainer-email: Vladislav Shepilov <shepilov.v@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,framework-agnostic,principal,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <3.15.0,>=3.12.0
+Requires-Dist: anyio<5.0,>=4.14.2
+Description-Content-Type: text/markdown
+
+# authweave-core
+
+Framework-neutral contracts and fail-closed coordination for principal authentication.
+
+```bash
+uv add authweave-core
+```
+
+The package models verified principals, authentication evidence, immutable request projections,
+typed authentication decisions, provider ownership, route policies, and deadline-aware
+coordination. It does not depend on a web framework, ORM, cache, or cryptography implementation.
+
+`authweave-core` performs authentication orchestration only. Applications remain responsible for
+resource authorization.

authweave_core-7.0.0/README.md

@@ -0,0 +1,14 @@
+# authweave-core
+
+Framework-neutral contracts and fail-closed coordination for principal authentication.
+
+```bash
+uv add authweave-core
+```
+
+The package models verified principals, authentication evidence, immutable request projections,
+typed authentication decisions, provider ownership, route policies, and deadline-aware
+coordination. It does not depend on a web framework, ORM, cache, or cryptography implementation.
+
+`authweave-core` performs authentication orchestration only. Applications remain responsible for
+resource authorization.

authweave_core-7.0.0/authweave_core/__init__.py

@@ -0,0 +1,45 @@
+"""Framework-neutral principal authentication contracts."""
+
+from authweave_core.coordinator import AuthenticationCoordinator, RequestAuthenticationProvider
+from authweave_core.models import (
+    Authenticated,
+    AuthenticationContext,
+    AuthenticationDecision,
+    AuthenticationEvidence,
+    AuthenticationRuntime,
+    CredentialMatch,
+    EvidenceValue,
+    FailureCode,
+    Invalid,
+    InvariantFailure,
+    NotApplicable,
+    PrincipalRef,
+    RequestView,
+    RouteProviderPolicy,
+    TlsPeerEvidence,
+    Unavailable,
+)
+
+__version__ = "7.0.0"
+
+__all__ = (
+    "Authenticated",
+    "AuthenticationContext",
+    "AuthenticationCoordinator",
+    "AuthenticationDecision",
+    "AuthenticationEvidence",
+    "AuthenticationRuntime",
+    "CredentialMatch",
+    "EvidenceValue",
+    "FailureCode",
+    "Invalid",
+    "InvariantFailure",
+    "NotApplicable",
+    "PrincipalRef",
+    "RequestAuthenticationProvider",
+    "RequestView",
+    "RouteProviderPolicy",
+    "TlsPeerEvidence",
+    "Unavailable",
+    "__version__",
+)

authweave_core-7.0.0/authweave_core/coordinator.py

@@ -0,0 +1,148 @@
+"""Fail-closed authentication provider coordination."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+import anyio
+
+from authweave_core.models import (
+    Authenticated,
+    AuthenticationDecision,
+    AuthenticationRuntime,
+    CredentialMatch,
+    FailureCode,
+    Invalid,
+    InvariantFailure,
+    NotApplicable,
+    RequestView,
+    RouteProviderPolicy,
+    Unavailable,
+    _validate_label,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+@runtime_checkable
+class RequestAuthenticationProvider(Protocol):
+    """Framework-neutral request authentication provider."""
+
+    name: str
+    profile: str
+
+    def match(self, request: RequestView) -> CredentialMatch:
+        """Classify credential ownership without performing expensive verification."""
+        ...
+
+    async def authenticate(
+        self,
+        request: RequestView,
+        runtime: AuthenticationRuntime,
+    ) -> AuthenticationDecision:
+        """Verify an owned credential presentation."""
+        ...
+
+
+class AuthenticationCoordinator:
+    """Route providers deterministically and stop on every owned failure."""
+
+    def __init__(self, providers: Iterable[RequestAuthenticationProvider]) -> None:
+        """Freeze and validate the provider inventory.
+
+        Raises:
+            ValueError: If provider names or profiles are invalid or duplicated.
+        """
+        inventory = tuple(providers)
+        names: set[str] = set()
+        profiles: set[str] = set()
+        for provider in inventory:
+            _validate_label(provider.name, name="provider name")
+            _validate_label(provider.profile, name="provider profile")
+            if provider.name in names:
+                msg = f"duplicate provider name: {provider.name}"
+                raise ValueError(msg)
+            if provider.profile in profiles:
+                msg = f"duplicate provider profile: {provider.profile}"
+                raise ValueError(msg)
+            names.add(provider.name)
+            profiles.add(provider.profile)
+        self._providers = {provider.name: provider for provider in inventory}
+
+    async def authenticate(
+        self,
+        request: RequestView,
+        runtime: AuthenticationRuntime,
+        policy: RouteProviderPolicy,
+    ) -> AuthenticationDecision:
+        """Authenticate through exactly one credential owner.
+
+        Returns:
+            A terminal typed authentication decision.
+        """
+        selected = self._select_provider(request, policy)
+        if not isinstance(selected, RequestAuthenticationProvider):
+            return selected
+
+        decision = await self._authenticate_with_deadline(selected, request, runtime)
+        return self._validate_decision(selected, decision)
+
+    def _select_provider(
+        self,
+        request: RequestView,
+        policy: RouteProviderPolicy,
+    ) -> RequestAuthenticationProvider | AuthenticationDecision:
+        allowed: list[RequestAuthenticationProvider] = []
+        for name in policy.providers:
+            provider = self._providers.get(name)
+            if provider is None:
+                return InvariantFailure()
+            match provider.match(request):
+                case CredentialMatch.NOT_APPLICABLE:
+                    continue
+                case CredentialMatch.OWNED:
+                    allowed.append(provider)
+                case CredentialMatch.AMBIGUOUS:
+                    return Invalid(FailureCode.AMBIGUOUS_CREDENTIALS)
+                case _:
+                    return InvariantFailure()
+        if not allowed:
+            return NotApplicable()
+        return allowed[0]
+
+    @staticmethod
+    def _validate_decision(
+        provider: RequestAuthenticationProvider,
+        decision: object,
+    ) -> AuthenticationDecision:
+        if isinstance(decision, NotApplicable):
+            return InvariantFailure()
+        if isinstance(decision, Authenticated):
+            evidence = decision.context.evidence
+            if evidence.provider != provider.name or evidence.profile != provider.profile:
+                return InvariantFailure()
+        if not isinstance(decision, (Authenticated, Invalid, Unavailable, InvariantFailure)):
+            return InvariantFailure()
+        return decision
+
+    @staticmethod
+    async def _authenticate_with_deadline(
+        provider: RequestAuthenticationProvider,
+        request: RequestView,
+        runtime: AuthenticationRuntime,
+    ) -> AuthenticationDecision:
+        """Apply the request deadline without swallowing external cancellation.
+
+        Returns:
+            Provider decision or unavailable when the deadline expires.
+        """
+        if runtime.deadline is None:
+            return await provider.authenticate(request, runtime)
+
+        remaining = runtime.deadline - anyio.current_time()
+        if remaining <= 0:
+            return Unavailable()
+        with anyio.move_on_after(remaining) as timeout_scope:
+            decision = await provider.authenticate(request, runtime)
+        return Unavailable() if timeout_scope.cancelled_caught else decision

authweave_core-7.0.0/authweave_core/models.py

@@ -0,0 +1,357 @@
+"""Immutable contracts shared by authentication providers and adapters."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_LABEL_PATTERN = re.compile(r"^[a-z][a-z0-9_.-]{0,63}$")
+_EXTENSION_KEY_PATTERN = re.compile(r"^[a-z][a-z0-9_.-]{0,62}:[a-z][a-z0-9_.-]{0,62}$")
+_HTTP_TOKEN_PATTERN = re.compile(rb"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
+_THUMBPRINT_PATTERN = re.compile(r"^[A-Za-z0-9_-]{43}$")
+_MAX_ISSUER_LENGTH = 2048
+_MAX_SUBJECT_LENGTH = 512
+_MAX_VALUE_LENGTH = 512
+_MAX_EXTENSIONS = 16
+_MAX_EVIDENCE_VALUES = 64
+_MAX_HEADERS = 128
+_MAX_HEADER_BYTES = 65_536
+
+type EvidenceValue = str | int | bool
+
+
+def _validate_text(value: str, *, name: str, max_length: int = _MAX_VALUE_LENGTH) -> None:
+    if not value or value != value.strip() or len(value) > max_length:
+        msg = f"{name} must be non-empty, trimmed, and at most {max_length} characters"
+        raise ValueError(msg)
+
+
+def _validate_label(value: str, *, name: str) -> None:
+    if _LABEL_PATTERN.fullmatch(value) is None:
+        msg = f"{name} must match {_LABEL_PATTERN.pattern!r}"
+        raise ValueError(msg)
+
+
+def _validate_aware(value: datetime | None, *, name: str) -> None:
+    if value is not None and value.utcoffset() is None:
+        msg = f"{name} must be timezone-aware"
+        raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class PrincipalRef:
+    """Stable principal identity with a verified classification."""
+
+    issuer: str
+    subject: str
+    kind: str
+
+    def __post_init__(self) -> None:
+        """Validate bounded identity components."""
+        _validate_text(self.issuer, name="issuer", max_length=_MAX_ISSUER_LENGTH)
+        _validate_text(self.subject, name="subject", max_length=_MAX_SUBJECT_LENGTH)
+        _validate_label(self.kind, name="kind")
+
+    def __eq__(self, other: object) -> bool:
+        """Compare stable identity independently from classification.
+
+        Returns:
+            Whether issuer and subject match.
+        """
+        if not isinstance(other, PrincipalRef):
+            return NotImplemented
+        return (self.issuer, self.subject) == (other.issuer, other.subject)
+
+    def __hash__(self) -> int:
+        """Hash the stable identity independently from classification.
+
+        Returns:
+            Hash of issuer and subject.
+        """
+        return hash((self.issuer, self.subject))
+
+
+@dataclass(frozen=True, slots=True)
+class TlsPeerEvidence:
+    """Verified TLS peer facts produced by a trusted termination boundary."""
+
+    tls_version: str
+    certificate_thumbprint: str
+    certificate_not_before: datetime
+    certificate_not_after: datetime
+    revocation_checked_at: datetime
+    trust_anchor: str
+    termination_boundary: str
+
+    def __post_init__(self) -> None:
+        """Reject malformed or internally inconsistent TLS evidence.
+
+        Raises:
+            ValueError: If a field is malformed or the validity interval is empty.
+        """
+        _validate_text(self.tls_version, name="tls_version", max_length=32)
+        if _THUMBPRINT_PATTERN.fullmatch(self.certificate_thumbprint) is None:
+            msg = "certificate_thumbprint must be an unpadded base64url SHA-256 digest"
+            raise ValueError(msg)
+        _validate_aware(self.certificate_not_before, name="certificate_not_before")
+        _validate_aware(self.certificate_not_after, name="certificate_not_after")
+        _validate_aware(self.revocation_checked_at, name="revocation_checked_at")
+        if self.certificate_not_before >= self.certificate_not_after:
+            msg = "certificate_not_before must be earlier than certificate_not_after"
+            raise ValueError(msg)
+        _validate_text(self.trust_anchor, name="trust_anchor")
+        _validate_text(self.termination_boundary, name="termination_boundary")
+
+
+@dataclass(frozen=True, slots=True)
+class RequestView:
+    """Immutable, framework-neutral projection of authentication inputs."""
+
+    method: str
+    headers: tuple[tuple[bytes, bytes], ...] = field(default=(), repr=False)
+    scheme: str | None = None
+    authority: str | None = None
+    tls_peer: TlsPeerEvidence | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    correlation_id: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate request metadata without collapsing duplicate headers.
+
+        Raises:
+            ValueError: If request metadata is malformed.
+        """
+        try:
+            method = self.method.encode("ascii")
+        except UnicodeEncodeError as exc:
+            msg = "method must be an ASCII HTTP token"
+            raise ValueError(msg) from exc
+        if _HTTP_TOKEN_PATTERN.fullmatch(method) is None:
+            msg = "method must be an ASCII HTTP token"
+            raise ValueError(msg)
+        object.__setattr__(self, "headers", tuple(self.headers))
+        if (
+            len(self.headers) > _MAX_HEADERS
+            or sum(len(name) + len(value) for name, value in self.headers) > _MAX_HEADER_BYTES
+        ):
+            msg = "headers exceed the authentication projection limits"
+            raise ValueError(msg)
+        for name, value in self.headers:
+            if _HTTP_TOKEN_PATTERN.fullmatch(name) is None:
+                msg = "header names must be non-empty ASCII HTTP tokens"
+                raise ValueError(msg)
+            if b"\x00" in value or b"\r" in value or b"\n" in value:
+                msg = "header values must not contain NUL, CR, or LF"
+                raise ValueError(msg)
+        if self.scheme is not None:
+            _validate_text(self.scheme, name="scheme", max_length=32)
+        if self.authority is not None:
+            _validate_text(self.authority, name="authority", max_length=512)
+        _validate_aware(self.timestamp, name="timestamp")
+        if self.correlation_id is not None:
+            _validate_text(self.correlation_id, name="correlation_id")
+
+    def header_values(self, name: bytes) -> tuple[bytes, ...]:
+        """Return every value for a case-insensitive header name."""
+        normalized = name.lower()
+        return tuple(value for header_name, value in self.headers if header_name.lower() == normalized)
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticationEvidence:
+    """Verified, secret-free facts produced by an authentication provider."""
+
+    provider: str
+    profile: str
+    method: str
+    issuer: str
+    audiences: tuple[str, ...] = ()
+    scopes: tuple[str, ...] = ()
+    issued_at: datetime | None = None
+    not_before: datetime | None = None
+    expires_at: datetime | None = None
+    credential_id: str | None = None
+    token_id: str | None = None
+    confirmation_thumbprint: str | None = None
+    environment: str | None = None
+    extensions: Mapping[str, EvidenceValue] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate bounded evidence and freeze extension data."""
+        _validate_label(self.provider, name="provider")
+        _validate_label(self.profile, name="profile")
+        _validate_label(self.method, name="method")
+        _validate_text(self.issuer, name="issuer", max_length=_MAX_ISSUER_LENGTH)
+        object.__setattr__(self, "audiences", _freeze_evidence_values(self.audiences, name="audiences"))
+        object.__setattr__(self, "scopes", _freeze_evidence_values(self.scopes, name="scopes"))
+        _validate_evidence_times(self)
+        _validate_evidence_identifiers(self)
+        object.__setattr__(self, "extensions", _freeze_extensions(self.extensions))
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticationContext:
+    """Authenticated subject, actor, delegation chain, and verified evidence."""
+
+    subject: PrincipalRef
+    actor: PrincipalRef
+    evidence: AuthenticationEvidence
+    delegation_chain: tuple[PrincipalRef, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Freeze the delegation chain."""
+        object.__setattr__(self, "delegation_chain", tuple(self.delegation_chain))
+
+
+class FailureCode(StrEnum):
+    """Stable neutral authentication failure codes."""
+
+    MISSING = "missing"
+    MALFORMED = "malformed"
+    INVALID = "invalid"
+    EXPIRED = "expired"
+    NOT_YET_VALID = "not_yet_valid"
+    REVOKED = "revoked"
+    PRINCIPAL_DISABLED = "principal_disabled"
+    ISSUER_MISMATCH = "issuer_mismatch"
+    AUDIENCE_MISMATCH = "audience_mismatch"
+    TOKEN_TYPE_MISMATCH = "token_type_mismatch"
+    ALGORITHM_MISMATCH = "algorithm_mismatch"
+    SENDER_CONSTRAINT_MISMATCH = "sender_constraint_mismatch"
+    AMBIGUOUS_CREDENTIALS = "ambiguous_credentials"
+    PROVIDER_UNAVAILABLE = "provider_unavailable"
+    INTERNAL_INVARIANT = "internal_invariant"
+
+
+class CredentialMatch(StrEnum):
+    """Credential ownership result returned by a provider matcher."""
+
+    NOT_APPLICABLE = "not_applicable"
+    OWNED = "owned"
+    AMBIGUOUS = "ambiguous"
+
+
+@dataclass(frozen=True, slots=True)
+class NotApplicable:
+    """No allowed provider owns a credential presentation."""
+
+
+@dataclass(frozen=True, slots=True)
+class Authenticated:
+    """Credential was fully verified."""
+
+    context: AuthenticationContext
+
+
+@dataclass(frozen=True, slots=True)
+class Invalid:
+    """Credential was owned but failed verification."""
+
+    code: FailureCode
+
+
+@dataclass(frozen=True, slots=True)
+class Unavailable:
+    """Credential verification could not complete safely."""
+
+    code: FailureCode = FailureCode.PROVIDER_UNAVAILABLE
+
+
+@dataclass(frozen=True, slots=True)
+class InvariantFailure:
+    """Provider or coordinator contract was violated."""
+
+    code: FailureCode = field(default=FailureCode.INTERNAL_INVARIANT, init=False)
+
+
+type AuthenticationDecision = NotApplicable | Authenticated | Invalid | Unavailable | InvariantFailure
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticationRuntime:
+    """Request-scoped execution limits for providers."""
+
+    deadline: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RouteProviderPolicy:
+    """Ordered-free set of provider names permitted for a route."""
+
+    providers: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Validate and deduplicate provider names.
+
+        Raises:
+            ValueError: If a provider name is invalid or duplicated.
+        """
+        providers = tuple(self.providers)
+        for provider in providers:
+            _validate_label(provider, name="provider")
+        if len(providers) > 1:
+            msg = "route provider policy permits at most one authentication profile"
+            raise ValueError(msg)
+        object.__setattr__(self, "providers", providers)
+
+
+def _freeze_evidence_values(values: tuple[str, ...], *, name: str) -> tuple[str, ...]:
+    frozen = tuple(values)
+    if len(frozen) > _MAX_EVIDENCE_VALUES:
+        msg = f"{name} must contain at most {_MAX_EVIDENCE_VALUES} values"
+        raise ValueError(msg)
+    for value in frozen:
+        _validate_text(value, name=name)
+    return frozen
+
+
+def _validate_evidence_times(evidence: AuthenticationEvidence) -> None:
+    for name in ("issued_at", "not_before", "expires_at"):
+        _validate_aware(getattr(evidence, name), name=name)
+    if (
+        evidence.not_before is not None
+        and evidence.expires_at is not None
+        and evidence.not_before >= evidence.expires_at
+    ):
+        msg = "not_before must be earlier than expires_at"
+        raise ValueError(msg)
+
+
+def _validate_evidence_identifiers(evidence: AuthenticationEvidence) -> None:
+    for name in ("credential_id", "token_id", "environment"):
+        value = getattr(evidence, name)
+        if value is not None:
+            _validate_text(value, name=name)
+    if (
+        evidence.confirmation_thumbprint is not None
+        and _THUMBPRINT_PATTERN.fullmatch(
+            evidence.confirmation_thumbprint,
+        )
+        is None
+    ):
+        msg = "confirmation_thumbprint must be an unpadded base64url SHA-256 digest"
+        raise ValueError(msg)
+
+
+def _freeze_extensions(extensions: Mapping[str, EvidenceValue]) -> Mapping[str, EvidenceValue]:
+    frozen = dict(extensions)
+    if len(frozen) > _MAX_EXTENSIONS:
+        msg = f"extensions must contain at most {_MAX_EXTENSIONS} entries"
+        raise ValueError(msg)
+    for key, value in frozen.items():
+        if _EXTENSION_KEY_PATTERN.fullmatch(key) is None:
+            msg = f"extension key {key!r} must be namespaced"
+            raise ValueError(msg)
+        if isinstance(value, str):
+            _validate_text(value, name=f"extension {key}", max_length=256)
+        elif not isinstance(value, (bool, int)):
+            msg = f"extension {key!r} must contain a string, integer, or boolean"
+            raise TypeError(msg)
+    return MappingProxyType(frozen)

authweave_core-7.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "authweave-core"
+version = "7.0.0"
+description = "Framework-neutral principal authentication contracts and coordinator"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Vladislav Shepilov", email = "shepilov.v@protonmail.com"},
+]
+maintainers = [
+    {name = "Vladislav Shepilov", email = "shepilov.v@protonmail.com"},
+]
+keywords = ["authentication", "principal", "security", "framework-agnostic"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = "<3.15.0,>=3.12.0"
+dependencies = ["anyio>=4.14.2,<5.0"]
+
+[project.urls]
+homepage = "https://github.com/ZYLVEXT/litestar-auth"
+documentation = "https://zylvext.github.io/litestar-auth/"
+source = "https://github.com/ZYLVEXT/litestar-auth"
+tracker = "https://github.com/ZYLVEXT/litestar-auth/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["authweave_core"]
+artifacts = ["authweave_core/py.typed"]
+
+[tool.coverage.run]
+source = ["authweave_core"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.src]
+include = ["authweave_core", "tests"]

authweave_core-7.0.0/tests/__init__.py

@@ -0,0 +1 @@
+"""authweave-core tests."""

authweave_core-7.0.0/tests/test_coordinator.py

@@ -0,0 +1,203 @@
+"""Behavior tests for deterministic provider coordination."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import cast
+
+import anyio
+import pytest
+from authweave_core import (
+    Authenticated,
+    AuthenticationContext,
+    AuthenticationCoordinator,
+    AuthenticationDecision,
+    AuthenticationEvidence,
+    AuthenticationRuntime,
+    CredentialMatch,
+    FailureCode,
+    Invalid,
+    InvariantFailure,
+    NotApplicable,
+    PrincipalRef,
+    RequestView,
+    RouteProviderPolicy,
+    Unavailable,
+)
+
+pytestmark = pytest.mark.unit
+
+
+def _authenticated(*, provider: str = "provider", profile: str = "profile") -> Authenticated:
+    principal = PrincipalRef("issuer", "subject", "service")
+    evidence = AuthenticationEvidence(provider, profile, "mtls", "issuer")
+    return Authenticated(AuthenticationContext(principal, principal, evidence))
+
+
+@dataclass
+class _Provider:
+    name: str = "provider"
+    profile: str = "profile"
+    match_result: CredentialMatch | object = CredentialMatch.OWNED
+    decision: AuthenticationDecision | object = field(default_factory=_authenticated)
+    delay: float = 0
+    calls: int = 0
+
+    def match(self, request: RequestView) -> CredentialMatch:
+        return cast("CredentialMatch", self.match_result)
+
+    async def authenticate(
+        self,
+        request: RequestView,
+        runtime: AuthenticationRuntime,
+    ) -> AuthenticationDecision:
+        self.calls += 1
+        if self.delay:
+            await anyio.sleep(self.delay)
+        return cast("AuthenticationDecision", self.decision)
+
+
+def test_coordinator_rejects_duplicate_inventory() -> None:
+    with pytest.raises(ValueError, match="name"):
+        AuthenticationCoordinator((_Provider(), _Provider(profile="other")))
+    with pytest.raises(ValueError, match="profile"):
+        AuthenticationCoordinator((_Provider(), _Provider(name="other")))
+    with pytest.raises(ValueError, match="must match"):
+        AuthenticationCoordinator((_Provider(name="Not Valid"),))
+
+
+async def test_coordinator_returns_not_applicable_without_owned_credentials() -> None:
+    provider = _Provider(match_result=CredentialMatch.NOT_APPLICABLE)
+    coordinator = AuthenticationCoordinator((provider,))
+
+    result = await coordinator.authenticate(
+        RequestView("GET"),
+        AuthenticationRuntime(),
+        RouteProviderPolicy(("provider",)),
+    )
+
+    assert isinstance(result, NotApplicable)
+    assert provider.calls == 0
+
+
+def test_route_policy_rejects_overlapping_provider_profiles() -> None:
+    """A route cannot activate two credential owners."""
+    with pytest.raises(ValueError, match="at most one"):
+        RouteProviderPolicy(("first", "second"))
+
+
+@pytest.mark.parametrize(
+    "match_result",
+    [CredentialMatch.AMBIGUOUS, object()],
+)
+async def test_coordinator_fails_closed_for_invalid_match_result(match_result: CredentialMatch | object) -> None:
+    provider = _Provider(match_result=match_result)
+    coordinator = AuthenticationCoordinator((provider,))
+
+    result = await coordinator.authenticate(
+        RequestView("GET"),
+        AuthenticationRuntime(),
+        RouteProviderPolicy(("provider",)),
+    )
+
+    assert result in {Invalid(FailureCode.AMBIGUOUS_CREDENTIALS), InvariantFailure()}
+    assert provider.calls == 0
+
+
+async def test_coordinator_returns_config_invariant_for_unknown_provider() -> None:
+    result = await AuthenticationCoordinator(()).authenticate(
+        RequestView("GET"),
+        AuthenticationRuntime(),
+        RouteProviderPolicy(("missing",)),
+    )
+
+    assert isinstance(result, InvariantFailure)
+
+
+@pytest.mark.parametrize(
+    "decision",
+    [
+        Invalid(FailureCode.INVALID),
+        Unavailable(),
+        InvariantFailure(),
+    ],
+)
+async def test_coordinator_returns_terminal_provider_decision(decision: AuthenticationDecision) -> None:
+    provider = _Provider(decision=decision)
+    coordinator = AuthenticationCoordinator((provider,))
+
+    result = await coordinator.authenticate(
+        RequestView("GET"),
+        AuthenticationRuntime(),
+        RouteProviderPolicy(("provider",)),
+    )
+
+    assert result == decision
+    assert provider.calls == 1
+
+
+@pytest.mark.parametrize(
+    "decision",
+    [
+        NotApplicable(),
+        _authenticated(provider="other"),
+        _authenticated(profile="other"),
+        object(),
+    ],
+)
+async def test_coordinator_rejects_provider_contract_violations(decision: AuthenticationDecision | object) -> None:
+    provider = _Provider(decision=decision)
+    coordinator = AuthenticationCoordinator((provider,))
+
+    result = await coordinator.authenticate(
+        RequestView("GET"),
+        AuthenticationRuntime(),
+        RouteProviderPolicy(("provider",)),
+    )
+
+    assert isinstance(result, InvariantFailure)
+
+
+async def test_coordinator_returns_authenticated_context() -> None:
+    expected = _authenticated()
+    provider = _Provider(decision=expected)
+    coordinator = AuthenticationCoordinator((provider,))
+
+    result = await coordinator.authenticate(
+        RequestView("GET"),
+        AuthenticationRuntime(),
+        RouteProviderPolicy(("provider",)),
+    )
+
+    assert result == expected
+
+
+async def test_coordinator_enforces_expired_and_active_deadlines() -> None:
+    provider = _Provider(delay=1)
+    coordinator = AuthenticationCoordinator((provider,))
+    request = RequestView("GET")
+    policy = RouteProviderPolicy(("provider",))
+
+    expired = await coordinator.authenticate(request, AuthenticationRuntime(deadline=anyio.current_time()), policy)
+    timed_out = await coordinator.authenticate(
+        request,
+        AuthenticationRuntime(deadline=anyio.current_time() + 0.01),
+        policy,
+    )
+
+    assert isinstance(expired, Unavailable)
+    assert isinstance(timed_out, Unavailable)
+
+
+async def test_coordinator_does_not_swallow_external_cancellation() -> None:
+    provider = _Provider(delay=1)
+    coordinator = AuthenticationCoordinator((provider,))
+
+    with anyio.move_on_after(0.01) as scope:
+        await coordinator.authenticate(
+            RequestView("GET"),
+            AuthenticationRuntime(),
+            RouteProviderPolicy(("provider",)),
+        )
+
+    assert scope.cancel_called

authweave_core-7.0.0/tests/test_imports.py

@@ -0,0 +1,31 @@
+"""Import-isolation tests for authweave-core."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+import pytest
+
+pytestmark = pytest.mark.imports
+
+
+def test_base_import_does_not_load_framework_storage_or_crypto_packages() -> None:
+    script = """
+import json
+import sys
+import authweave_core
+
+blocked = ("litestar", "sqlalchemy", "redis", "jwt", "cryptography")
+print(json.dumps(sorted(name for name in sys.modules if name.split(".", 1)[0] in blocked)))
+"""
+
+    completed = subprocess.run(
+        [sys.executable, "-c", script],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    assert json.loads(completed.stdout) == []

authweave_core-7.0.0/tests/test_models.py

@@ -0,0 +1,261 @@
+"""Behavior tests for public authweave-core contracts."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any, cast
+
+import pytest
+from authweave_core import (
+    AuthenticationContext,
+    AuthenticationEvidence,
+    FailureCode,
+    InvariantFailure,
+    PrincipalRef,
+    RequestView,
+    RouteProviderPolicy,
+    TlsPeerEvidence,
+)
+
+pytestmark = pytest.mark.unit
+
+_NOW = datetime(2026, 7, 30, tzinfo=UTC)
+_THUMBPRINT = "A" * 43
+
+
+def test_principal_identity_is_issuer_and_subject() -> None:
+    human = PrincipalRef("https://issuer.example", "subject-1", "human")
+    service = PrincipalRef("https://issuer.example", "subject-1", "service")
+
+    assert human == service
+    assert len({human, service}) == 1
+    assert human != object()
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [
+        ("issuer", ""),
+        ("subject", " subject"),
+        ("kind", "Not Valid"),
+    ],
+)
+def test_principal_rejects_invalid_identity_components(field: str, value: str) -> None:
+    values = {"issuer": "issuer", "subject": "subject", "kind": "service", field: value}
+
+    with pytest.raises(ValueError, match="must"):
+        PrincipalRef(**cast("dict[str, Any]", values))
+
+
+def test_request_preserves_duplicate_headers_case_insensitively() -> None:
+    request = RequestView(
+        method="GET",
+        headers=((b"Authorization", b"one"), (b"authorization", b"two")),
+        timestamp=_NOW,
+    )
+
+    assert request.header_values(b"AUTHORIZATION") == (b"one", b"two")
+    assert request.header_values(b"missing") == ()
+
+
+def test_request_hides_credentials_and_bounds_headers() -> None:
+    token = b"secret-session-token"
+    request = RequestView(method="GET", headers=((b"cookie", token),), timestamp=_NOW)
+
+    assert token.decode() not in repr(request)
+    with pytest.raises(ValueError, match="projection limits"):
+        RequestView(method="GET", headers=tuple((b"x", b"1") for _ in range(129)), timestamp=_NOW)
+
+
+@pytest.mark.parametrize(
+    ("method", "headers"),
+    [
+        ("G ET", ()),
+        ("GÉT", ()),
+        ("GET", ((b"", b"value"),)),
+        ("GET", ((b"x-test", b"bad\rvalue"),)),
+        ("GET", ((b"x-test", b"bad\nvalue"),)),
+        ("GET", ((b"x-test", b"bad\x00value"),)),
+    ],
+)
+def test_request_rejects_malformed_http_metadata(
+    method: str,
+    headers: tuple[tuple[bytes, bytes], ...],
+) -> None:
+    with pytest.raises(ValueError, match="must"):
+        RequestView(method=method, headers=headers, timestamp=_NOW)
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [
+        ("scheme", ""),
+        ("authority", " host"),
+        ("correlation_id", ""),
+    ],
+)
+def test_request_rejects_invalid_optional_text(field: str, value: str) -> None:
+    values = {"method": "GET", "timestamp": _NOW, field: value}
+
+    with pytest.raises(ValueError, match="must"):
+        RequestView(**cast("dict[str, Any]", values))
+
+
+def test_request_requires_aware_timestamp() -> None:
+    with pytest.raises(ValueError, match="timezone-aware"):
+        RequestView(method="GET", timestamp=datetime(2026, 7, 30))
+
+
+def test_tls_peer_evidence_validates_thumbprint_and_times() -> None:
+    evidence = TlsPeerEvidence(
+        tls_version="TLSv1.3",
+        certificate_thumbprint=_THUMBPRINT,
+        certificate_not_before=_NOW,
+        certificate_not_after=_NOW + timedelta(hours=1),
+        revocation_checked_at=_NOW,
+        trust_anchor="ca:payments",
+        termination_boundary="envoy:ingress",
+    )
+
+    assert evidence.certificate_thumbprint == _THUMBPRINT
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [
+        ("tls_version", ""),
+        ("certificate_thumbprint", "not-a-thumbprint"),
+        ("trust_anchor", ""),
+        ("termination_boundary", ""),
+        ("certificate_not_before", datetime(2026, 7, 30)),
+        ("certificate_not_after", datetime(2026, 7, 30)),
+        ("revocation_checked_at", datetime(2026, 7, 30)),
+    ],
+)
+def test_tls_peer_evidence_rejects_invalid_fields(field: str, value: object) -> None:
+    values = {
+        "tls_version": "TLSv1.3",
+        "certificate_thumbprint": _THUMBPRINT,
+        "certificate_not_before": _NOW,
+        "certificate_not_after": _NOW + timedelta(hours=1),
+        "revocation_checked_at": _NOW,
+        "trust_anchor": "ca:payments",
+        "termination_boundary": "envoy:ingress",
+        field: value,
+    }
+
+    with pytest.raises(ValueError, match="must"):
+        TlsPeerEvidence(**values)
+
+
+def test_tls_peer_evidence_rejects_reversed_validity() -> None:
+    with pytest.raises(ValueError, match="earlier"):
+        TlsPeerEvidence(
+            tls_version="TLSv1.3",
+            certificate_thumbprint=_THUMBPRINT,
+            certificate_not_before=_NOW,
+            certificate_not_after=_NOW,
+            revocation_checked_at=_NOW,
+            trust_anchor="ca:payments",
+            termination_boundary="envoy:ingress",
+        )
+
+
+def test_authentication_evidence_is_bounded_and_immutable() -> None:
+    extensions: dict[str, str | int | bool] = {
+        "example:risk": "low",
+        "example:score": 7,
+        "example:reviewed": True,
+    }
+    evidence = AuthenticationEvidence(
+        provider="service_mtls",
+        profile="direct_mtls",
+        method="mtls",
+        issuer="urn:example:payments",
+        audiences=("payments",),
+        scopes=("payments.read",),
+        issued_at=_NOW,
+        not_before=_NOW,
+        expires_at=_NOW + timedelta(hours=1),
+        credential_id="credential-1",
+        token_id="token-1",
+        confirmation_thumbprint=_THUMBPRINT,
+        environment="sandbox",
+        extensions=extensions,
+    )
+    extensions["example:risk"] = "high"
+
+    assert evidence.extensions == {
+        "example:risk": "low",
+        "example:score": 7,
+        "example:reviewed": True,
+    }
+    with pytest.raises(TypeError):
+        cast("dict[str, str | int | bool]", evidence.extensions)["example:risk"] = "high"
+
+
+@pytest.mark.parametrize(
+    ("field", "value", "exception"),
+    [
+        ("provider", "Not Valid", ValueError),
+        ("audiences", ("",), ValueError),
+        ("scopes", tuple(str(index) for index in range(65)), ValueError),
+        ("issued_at", datetime(2026, 7, 30), ValueError),
+        ("confirmation_thumbprint", "bad", ValueError),
+        ("extensions", {"not-namespaced": "value"}, ValueError),
+        ("extensions", {"example:value": object()}, TypeError),
+        ("extensions", {f"example:{index}": index for index in range(17)}, ValueError),
+    ],
+)
+def test_authentication_evidence_rejects_invalid_data(
+    field: str,
+    value: object,
+    exception: type[Exception],
+) -> None:
+    values = {
+        "provider": "service_mtls",
+        "profile": "direct_mtls",
+        "method": "mtls",
+        "issuer": "urn:example:payments",
+        field: value,
+    }
+
+    with pytest.raises(exception):
+        AuthenticationEvidence(**cast("dict[str, Any]", values))
+
+
+def test_authentication_evidence_rejects_reversed_time_window() -> None:
+    with pytest.raises(ValueError, match="earlier"):
+        AuthenticationEvidence(
+            provider="service_mtls",
+            profile="direct_mtls",
+            method="mtls",
+            issuer="urn:example:payments",
+            not_before=_NOW,
+            expires_at=_NOW,
+        )
+
+
+def test_context_and_route_policy_freeze_inputs() -> None:
+    principal = PrincipalRef("issuer", "subject", "service")
+    evidence = AuthenticationEvidence("provider", "profile", "mtls", "issuer")
+    chain = [PrincipalRef("issuer", "actor", "agent")]
+    context = AuthenticationContext(principal, chain[0], evidence, cast("tuple[PrincipalRef, ...]", chain))
+    providers = ["provider"]
+    policy = RouteProviderPolicy(cast("tuple[str, ...]", providers))
+    chain.clear()
+    providers.clear()
+
+    assert len(context.delegation_chain) == 1
+    assert policy.providers == ("provider",)
+    assert InvariantFailure().code is FailureCode.INTERNAL_INVARIANT
+
+
+def test_route_policy_rejects_invalid_or_duplicate_names() -> None:
+    with pytest.raises(ValueError, match="must match"):
+        RouteProviderPolicy(("Not Valid",))
+    with pytest.raises(ValueError, match="at most one"):
+        RouteProviderPolicy(("provider", "provider"))
+
+    with pytest.raises(ValueError, match="at most one"):
+        RouteProviderPolicy(("provider", "other"))