loom-kernel 0.18.2__tar.gz → 1.0.0__tar.gz

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/CHANGELOG.md

@@ -1,3 +1,32 @@
+# 🚀 Release 1.0.0 ([#106](https://github.com/the-reacher-data/loom-py/pull/106)) ([`f8fe343`](https://github.com/the-reacher-data/loom-py/commit/f8fe3433a841711f2393c0def0c1796c1f3b05d8))
+
+
+
+
+
+
+
+
+
+
+## 🔖 Other
+- and* signs. Public keys stay inline -- they only verify.<br>
+  > The signing key is probed once at construction, so a malformed PEM or a key that
+  > cannot serve the configured algorithm fails startup. Reading the key is not
+  > parsing it: `cryptography` raises a plain `ValueError`, which is neither a
+  > `PyJWTError` nor what the port documents `ValueError` to mean, so without the
+  > probe a broken deployment surfaced at the first login disguised as a bad login.
+  > Verification accepts a map of public keys selected by the token's `kid`, so a
+  > key can be rotated with an overlap window instead of a restart that invalidates
+  > every live token. The key is chosen by `kid` and never by trying each in turn:
+  > exhaustive trial would decouple every algorithm from its key family, which is
+  > what keeps algorithm confusion impossible.
+  > BREAKING CHANGE: `JwtAuthConfig.public_key: str` is now
+  > `public_keys: dict[str, str]`, keyed by `kid`; `JwtAuthConfig.secret: str` is
+  > now `secret_path: str`, the path of a file holding the secret; and
+  > `verification_key` is a method taking a `kid` instead of a property. Config
+
+
 # 🚀 Release 0.18.2 ([#105](https://github.com/the-reacher-data/loom-py/pull/105)) ([`833a45d`](https://github.com/the-reacher-data/loom-py/commit/833a45db6cb8f2870f131eb54a80b12fbf06dd30))
 
 

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loom-kernel
-Version: 0.18.2
+Version: 1.0.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/docs/rest/identity.md

@@ -148,7 +148,7 @@ app:
   rest:
     auth:
       jwt:
-        secret: ${oc.env:LOOM_JWT_SECRET}
+        secret_path: ${oc.env:LOOM_JWT_SECRET_PATH}
         algorithms: [HS256]
         audience: loom-api
         roles_claim: loom_roles

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/docs/rest/sql.md

@@ -447,8 +447,9 @@ app:
   rest:
     auth:
       jwt:
-        secret: ${oc.env:LOOM_JWT_SECRET}   # HS256 — mutually exclusive with public_key
-        # public_key: ${oc.env:LOOM_JWT_PUBLIC_KEY_PEM}  # RS256/ES256 static PEM
+        secret_path: ${oc.env:LOOM_JWT_SECRET_PATH}   # HS256 — a path, not the value
+        # public_keys:                      # RS256/ES256/EdDSA — one PEM per key id
+        #   "2026-08": ${oc.env:LOOM_JWT_PUBLIC_KEY_PEM}
         algorithms: [HS256]                 # explicit allowlist; 'none' always rejected
         audience: loom-api                  # REQUIRED by any sql_endpoint with auth: identity
         issuer: null                        # validated only when set
@@ -463,8 +464,21 @@ app:
   needed; early token revocation is out of scope.
 - **`sub` is mandatory.** A token without a subject carries no identity to authorize
   against, nor to audit afterwards, so it is rejected with 401.
-- Exactly one of `secret` (HS*) or `public_key` (RS*/ES* static PEM) must be set, and
-  the algorithm allowlist must match the key type — validated fail-fast at startup.
+- Exactly one of `secret_path` (HS*) or `public_keys` (RS*/ES*/EdDSA static PEMs, keyed by
+  key id) must be set, and the algorithm allowlist must match the key type — validated
+  fail-fast at startup.
+- **`secret_path` is a path, not the value.** The config is a `msgspec.Struct`, so any
+  serializer emits its fields verbatim: holding an HS secret would let a config dump
+  publish the key that both verifies *and* signs. Public keys are safe to inline
+  because they only verify. The container has to materialize the value to a file:
+  Kubernetes mounts a `Secret` as a volume directly, while ECS/Fargate injects
+  task-definition secrets as **environment variables only**, so there an entrypoint
+  must write the value to a path on a `tmpfs` volume before the app starts.
+- With `public_keys`, the key is chosen by the token's `kid` header, never by trying
+  each key in turn: exhaustive trial would decouple every algorithm from its key
+  family, which is what makes algorithm confusion impossible here. A token with no
+  `kid` verifies only when a single key is configured, so a rotation overlap needs the
+  issuer to stamp one.
 - On success the verified claims are projected onto an
   {class}`~loom.core.identity.Identity` published for the request; on failure
   the response is a 401 with the standard error body, a `WWW-Authenticate` challenge

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "0.18.2"
+version = "1.0.0"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -132,7 +132,7 @@ dev = [
     "pyright>=1.1.390,<2.0",
     "pytest>=8.3.0",
     "pytest-asyncio>=0.24.0",
-    "pyjwt>=2.12.0",
+    "pyjwt[crypto]>=2.12.0",
     "redis>=5.0.0",
     "ruff>=0.9.0,<1.0",
     "sqlalchemy>=2.0,<3.0",
@@ -278,7 +278,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.18.2"
+version = "1.0.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/src/loom/core/identity/__init__.py

@@ -8,10 +8,13 @@ no transport and no infrastructure.
 
 from loom.core.identity.context import current_identity, reset_identity, set_identity
 from loom.core.identity.identity import ANONYMOUS, Identity
+from loom.core.identity.issuer import IssuedToken, TokenIssuer
 
 __all__ = [
     "ANONYMOUS",
     "Identity",
+    "IssuedToken",
+    "TokenIssuer",
     "current_identity",
     "reset_identity",
     "set_identity",

loom_kernel-1.0.0/src/loom/core/identity/issuer.py

@@ -0,0 +1,70 @@
+"""Minting a credential for a verified :class:`Identity`.
+
+The port lives beside the identity it consumes, not beside the transport that
+implements it: the caller is a login use case, so putting the abstraction in
+``loom.rest`` would make the application layer import infrastructure.  What is
+domain here is *"this service needs to mint a credential for this identity"*;
+that a JWT comes out is the detail, and it belongs to the implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Protocol
+
+from loom.core.identity.identity import Identity
+
+
+@dataclass(frozen=True, slots=True)
+class IssuedToken:
+    """A minted credential together with what the issuer already knew about it.
+
+    Returned instead of a bare string so a login endpoint never has to decode
+    the token it just signed: the expiry the HTTP response advertises and the
+    identifier the audit trail records are both produced by the signing step.
+
+    Attributes:
+        token: The encoded credential, ready to travel as a bearer token.
+        expires_at: Instant the credential stops being valid, timezone-aware.
+        jti: Unique identifier of this minting, for correlation and audit.
+    """
+
+    token: str
+    expires_at: datetime
+    jti: str
+
+
+class TokenIssuer(Protocol):
+    """Mints a credential that an :class:`Authenticator` can later verify.
+
+    Implementations guarantee the round trip: whatever the identity carries —
+    subject, roles and attributes — a matching authenticator recovers intact.
+    Everything the credential says comes from the identity, so no caller can
+    smuggle a claim past it.
+
+    Example::
+
+        issued = issuer.issue(identity)
+        response = {"access_token": issued.token, "expires_at": issued.expires_at}
+    """
+
+    def issue(self, identity: Identity, *, ttl: timedelta | None = None) -> IssuedToken:
+        """Mint a credential for *identity*.
+
+        Args:
+            identity: Verified caller the credential speaks for.
+            ttl: Lifetime override. ``None`` uses the configured one, which is
+                also the ceiling: a longer lifetime is refused.
+
+        Returns:
+            The minted credential and its metadata.
+
+        Raises:
+            ValueError: If the identity cannot be represented — anonymous, or
+                carrying an attribute that would be unreadable once encoded —
+                or if *ttl* exceeds the configured lifetime.
+            RuntimeError: If the credential cannot be produced. Implementations
+                keep the cause out of the traceback: it can carry key material.
+        """
+        ...

{loom_kernel-0.18.2 → loom_kernel-1.0.0}/src/loom/rest/auth/__init__.py

@@ -13,8 +13,8 @@ Install the optional JWT dependency with::
 """
 
 from loom.rest.auth.abc import Authenticator, RequestCredentials
-from loom.rest.auth.config import JwtAuthConfig
-from loom.rest.auth.jwt import JwtAuthenticator
+from loom.rest.auth.config import JwtAuthConfig, JwtIssuerConfig
+from loom.rest.auth.jwt import JwtAuthenticator, JwtIssuer
 from loom.rest.auth.middleware import AuthenticationMiddleware, JwtAuthMiddleware
 
 __all__ = [
@@ -23,5 +23,7 @@ __all__ = [
     "JwtAuthConfig",
     "JwtAuthMiddleware",
     "JwtAuthenticator",
+    "JwtIssuer",
+    "JwtIssuerConfig",
     "RequestCredentials",
 ]

loom_kernel-1.0.0/src/loom/rest/auth/config.py

@@ -0,0 +1,317 @@
+"""Configuration for the native stateless JWT authentication middleware."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loom.core.config.errors import ConfigError
+from loom.core.model import LoomFrozenStruct
+
+DEFAULT_EXCLUDE_PATHS: tuple[str, ...] = ("/docs", "/redoc", "/openapi.json", "/metrics")
+"""Paths served without authentication unless the application says otherwise."""
+
+_FORBIDDEN_ALGORITHM = "none"
+
+MAX_ISSUER_TTL_SECONDS = 3600
+"""Ceiling for a minted token: signing is reading, so a long-lived token is a
+standing grant that stateless verification cannot revoke."""
+
+SUPPORTED_ALGORITHMS: frozenset[str] = frozenset(
+    {
+        "EdDSA",
+        "ES256",
+        "ES384",
+        "ES512",
+        "HS256",
+        "HS384",
+        "HS512",
+        "PS256",
+        "PS384",
+        "PS512",
+        "RS256",
+        "RS384",
+        "RS512",
+    }
+)
+"""Algorithms this framework signs with, checked at startup rather than on the
+first request: a typo like ``" HS256"`` would otherwise fail per-call."""
+
+
+# RFC 7519 registered claims: a roles claim named after one of these is silently
+# overwritten when the token is built, leaving no roles and no error.
+RESERVED_CLAIMS: frozenset[str] = frozenset({"iss", "sub", "aud", "exp", "nbf", "iat", "jti"})
+
+
+def _is_symmetric(algorithm: str) -> bool:
+    """Return ``True`` when *algorithm* uses a shared secret (HS* family)."""
+    return algorithm.upper().startswith("HS")
+
+
+def _require_supported(algorithm: str, *, setting: str) -> None:
+    """Reject ``none`` and anything outside the supported set, at startup.
+
+    Shared by both configs on purpose: a hardening applied to one and not the
+    other is how the two drift apart.
+    """
+    if algorithm.lower() == _FORBIDDEN_ALGORITHM:
+        raise ConfigError("The 'none' JWT algorithm is always forbidden.")
+    if algorithm not in SUPPORTED_ALGORITHMS:
+        raise ConfigError(
+            f"{setting} {algorithm!r} is not supported. "
+            f"Choose one of: {', '.join(sorted(SUPPORTED_ALGORITHMS))}."
+        )
+
+
+def _read_key_file(path: str, *, setting: str) -> str:
+    """Read key material from disk, never chaining the cause.
+
+    An ``OSError`` message carries the path and a ``UnicodeDecodeError`` carries
+    the whole file on ``exc.object``: either would publish key material through a
+    traceback or a structured log that serializes the exception.
+    """
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        raise ConfigError(f"Could not read {setting}.") from None
+
+
+def _require_usable_roles_claim(roles_claim: str) -> None:
+    """Reject a roles claim that is blank or shadows a registered claim."""
+    if not roles_claim or not roles_claim.strip():
+        raise ConfigError("JWT issuer requires a non-blank 'roles_claim'.")
+    if roles_claim in RESERVED_CLAIMS:
+        raise ConfigError(
+            f"JWT issuer 'roles_claim' {roles_claim!r} is a registered claim: "
+            "the token would carry no roles and raise nothing."
+        )
+
+
+class JwtAuthConfig(LoomFrozenStruct, frozen=True, kw_only=True):
+    """Validated settings for :class:`~loom.rest.auth.JwtAuthMiddleware`.
+
+    Binds from the ``app.rest.auth.jwt`` config section.  Validation runs on
+    construction (fail-fast): exactly one key source must be provided and the
+    algorithm allowlist must be non-empty and coherent with that key source.
+
+    Attributes:
+        secret_path: Filesystem path of the shared secret for symmetric
+            algorithms (HS*).  A path and not the value: this is a
+            ``msgspec.Struct``, so any serializer emits its fields verbatim and a
+            config dump would publish the key that verifies *and signs*.
+            Mutually exclusive with ``public_keys``.
+        public_keys: Static PEM-encoded public keys for asymmetric algorithms
+            (RS*/ES*/EdDSA), keyed by the ``kid`` that selects them.  Mutually
+            exclusive with ``secret``.
+        algorithms: Explicit allowlist of accepted JWT algorithms.  The
+            ``none`` algorithm is always forbidden.
+        audience: Expected ``aud`` claim.  Validated only when set.
+        issuer: Expected ``iss`` claim.  Validated only when set.
+        leeway_seconds: Clock-skew tolerance applied to time-based claims.
+        exclude_paths: Exact request paths that bypass authentication.
+        roles_claim: Name of the verified claim carrying the roles the caller
+            is authorized to use.  Consumed by the SQL endpoint: the effective
+            roles are the claim values intersected with the connection
+            allowlist, and the request body can only narrow that set.
+
+    Raises:
+        ConfigError: If key sources, algorithms, leeway, or the roles claim
+            name are invalid.
+
+    Example YAML::
+
+        app:
+          rest:
+            auth:
+              jwt:
+                secret_path: ${oc.env:LOOM_JWT_SECRET_PATH}
+                algorithms: [HS256]
+                roles_claim: loom_sql_roles
+    """
+
+    secret_path: str | None = None
+    public_keys: dict[str, str] = {}
+    algorithms: tuple[str, ...] = ()
+    audience: str | None = None
+    issuer: str | None = None
+    leeway_seconds: int = 0
+    exclude_paths: tuple[str, ...] = DEFAULT_EXCLUDE_PATHS
+    roles_claim: str | None = None
+
+    def __repr__(self) -> str:
+        return (
+            f"JwtAuthConfig(secret_path={self.secret_path!r},"
+            f" public_keys={sorted(self.public_keys)!r},"
+            f" algorithms={self.algorithms!r},"
+            f" audience={self.audience!r},"
+            f" issuer={self.issuer!r},"
+            f" leeway_seconds={self.leeway_seconds!r},"
+            f" exclude_paths={self.exclude_paths!r},"
+            f" roles_claim={self.roles_claim!r})"
+        )
+
+    def __post_init__(self) -> None:
+        if (self.secret_path is None) == (not self.public_keys):
+            raise ConfigError("JWT auth requires exactly one of 'secret_path' or 'public_keys'.")
+        for key_id, material in self.public_keys.items():
+            if not key_id.strip() or not material.strip():
+                raise ConfigError("JWT auth 'public_keys' entries need a key id and material.")
+        if not self.algorithms:
+            raise ConfigError("JWT auth requires a non-empty 'algorithms' allowlist.")
+        if self.leeway_seconds < 0:
+            raise ConfigError("JWT auth 'leeway_seconds' must be >= 0.")
+        if self.roles_claim is not None and not self.roles_claim.strip():
+            raise ConfigError("JWT auth 'roles_claim' must not be blank.")
+        for algorithm in self.algorithms:
+            self._validate_algorithm(algorithm)
+
+    def _validate_algorithm(self, algorithm: str) -> None:
+        _require_supported(algorithm, setting="JWT auth 'algorithms' entry")
+        if _is_symmetric(algorithm) and self.secret_path is None:
+            raise ConfigError(
+                f"JWT algorithm {algorithm!r} requires 'secret_path', not 'public_keys'."
+            )
+        if not _is_symmetric(algorithm) and not self.public_keys:
+            raise ConfigError(f"JWT algorithm {algorithm!r} requires 'public_keys', not 'secret'.")
+
+    def verification_key(self, key_id: str | None) -> str | None:
+        """Return the key that verifies a token, selected by its ``kid``.
+
+        Selection is explicit and never exhaustive: trying every configured key
+        in turn would decouple each algorithm from its key family, which is what
+        makes algorithm confusion structurally impossible here.
+
+        Args:
+            key_id: ``kid`` header of the token, or ``None`` when it carries none.
+
+        Returns:
+            The key material, or ``None`` when no configured key applies — an
+            unknown ``kid``, or a missing one while several keys are configured.
+        """
+        if self.secret_path is not None:
+            return _read_key_file(self.secret_path, setting="JWT auth 'secret_path'")
+        if key_id is not None:
+            return self.public_keys.get(key_id)
+        if len(self.public_keys) == 1:
+            return next(iter(self.public_keys.values()))
+        return None
+
+
+class JwtIssuerConfig(LoomFrozenStruct, frozen=True, kw_only=True):
+    """Validated settings for :class:`~loom.rest.auth.JwtIssuer`.
+
+    Separate from :class:`JwtAuthConfig` on purpose, and not a few extra fields
+    on it: a service that only verifies must have no configuration path through
+    which signing material can land in its process.  The fields diverge anyway —
+    one algorithm instead of an allowlist, ``audience`` and ``issuer`` mandatory
+    rather than optional, a lifetime the verifier has no use for.
+
+    The private key is read from ``private_key_path`` and never held as a field.
+    ``__repr__`` redaction would not be enough: this is a ``msgspec.Struct``, so
+    ``msgspec.json.encode`` and ``to_builtins`` emit every field verbatim without
+    going through it, and a config dump would publish the signing key.
+
+    Attributes:
+        private_key_path: Filesystem path of the PEM signing key, for
+            asymmetric algorithms. Mutually exclusive with ``secret``.
+        secret_path: Filesystem path of the shared secret for HS* algorithms.
+            Requires ``allow_symmetric_signing``. Mutually exclusive with
+            ``private_key_path``.
+        algorithm: The single algorithm tokens are signed with. Issuing chooses
+            one; only verification negotiates an allowlist.
+        audience: ``aud`` stamped on every token. Mandatory: a token without an
+            audience is valid at any service that shares the key.
+        issuer: ``iss`` stamped on every token. Mandatory.
+        roles_claim: Claim carrying the caller roles. Mandatory, and never a
+            registered claim: an issuer that does not own that name lets an
+            attribute impersonate it. An identity without roles is refused.
+        ttl_seconds: Lifetime of a minted token, in ``1..MAX_ISSUER_TTL_SECONDS``,
+            and the ceiling for any per-call override.
+        kid: Key identifier stamped on the token header, so a verifier can
+            select the right key during a rotation overlap.
+        allow_symmetric_signing: Opt-in required for HS*. With a shared secret
+            every verifier can also mint, so the choice must be deliberate.
+
+    Raises:
+        ConfigError: If key sources, algorithm, audience, issuer, roles claim
+            or lifetime are invalid.
+
+    Note:
+        Built programmatically, not bound from a config section: issuing happens in
+        an application use case that injects the issuer, not in the REST layer that
+        owns ``app.rest.auth``. Resolve the values however the service resolves its
+        own settings.
+
+    Example::
+
+        config = JwtIssuerConfig(
+            private_key_path=os.environ["JWT_SIGNING_KEY_PATH"],
+            algorithm="EdDSA",
+            audience="my-api",
+            issuer="my-gateway",
+            roles_claim="loom_sql_roles",
+            ttl_seconds=900,
+            kid="2026-08",
+        )
+    """
+
+    private_key_path: str | None = None
+    secret_path: str | None = None
+    algorithm: str = ""
+    audience: str = ""
+    issuer: str = ""
+    roles_claim: str = ""
+    ttl_seconds: int = 900
+    kid: str | None = None
+    allow_symmetric_signing: bool = False
+
+    def __post_init__(self) -> None:
+        if (self.private_key_path is None) == (self.secret_path is None):
+            raise ConfigError(
+                "JWT issuer requires exactly one of 'private_key_path' or 'secret_path'."
+            )
+        _require_supported(self.algorithm, setting="JWT issuer 'algorithm'")
+        if not self.audience.strip():
+            raise ConfigError("JWT issuer requires a non-blank 'audience'.")
+        if not self.issuer.strip():
+            raise ConfigError("JWT issuer requires a non-blank 'issuer'.")
+        # Optional here is what let an attribute impersonate the verifier's roles
+        # claim: the issuer must always own that name.
+        _require_usable_roles_claim(self.roles_claim)
+        if self.kid is not None and not self.kid.strip():
+            raise ConfigError("JWT issuer 'kid' must not be blank.")
+        if not 0 < self.ttl_seconds <= MAX_ISSUER_TTL_SECONDS:
+            raise ConfigError(f"JWT issuer 'ttl_seconds' must be in 1..{MAX_ISSUER_TTL_SECONDS}.")
+        self._validate_signing_material()
+
+    def _validate_signing_material(self) -> None:
+        symmetric = _is_symmetric(self.algorithm)
+        if symmetric and not self.allow_symmetric_signing:
+            raise ConfigError(
+                f"JWT algorithm {self.algorithm!r} shares one key between signer and "
+                "verifier, so every verifier could also mint. Set "
+                "'allow_symmetric_signing' to accept that."
+            )
+        if symmetric and self.secret_path is None:
+            raise ConfigError(
+                f"JWT algorithm {self.algorithm!r} requires 'secret_path', not 'private_key_path'."
+            )
+        if not symmetric and self.private_key_path is None:
+            raise ConfigError(
+                f"JWT algorithm {self.algorithm!r} requires 'private_key_path', not 'secret_path'."
+            )
+
+    def load_signing_key(self) -> str:
+        """Read the signing key, so it lives in the issuer and not in the config.
+
+        Returns:
+            The key material read from disk.
+
+        Raises:
+            ConfigError: If the file cannot be read or is not UTF-8 text. The
+                cause is never chained: an OS error carries the path, and a
+                ``UnicodeDecodeError`` carries the file contents on ``exc.object``.
+        """
+        source = self.secret_path or self.private_key_path
+        if source is None:  # pragma: no cover - __post_init__ rules this out
+            raise ConfigError("JWT issuer has no signing key configured.")
+        return _read_key_file(source, setting="the JWT issuer signing key")