coding-client 1.21.2__py3-none-any.whl

coding_client/auth/_default_tenant.py

@@ -0,0 +1,132 @@
+"""Resolution of the fallback tenant handed to credential-less callers.
+
+``DEFAULT_TENANT_ID`` is the tenant granted to a caller that presented **no
+credential** and was admitted anyway — the ``TRUSTED_CIDRS`` bypass in
+:mod:`._trusted_networks`, and the development/testing API-key path in
+:mod:`.middleware`. It is therefore a data-isolation key chosen by
+configuration, not by the caller.
+
+Why there is no default value (changed 2026-07-30)
+--------------------------------------------------
+This module-level constant used to be::
+
+    DEFAULT_TENANT_ID = os.getenv("DEFAULT_TENANT_ID", "n8n-dev")
+
+so a service that never set the variable minted users against the literal
+string ``"n8n-dev"``. That literal is not junk and it is not a real tenant_id
+either, which is exactly what made it dangerous:
+
+* ``n8n-dev`` **was** a real tenant — as a *text* tenant_id, until the
+  2026-04-29 Keycloak migration moved tenant identity to uuid7 and demoted the
+  label to a separate ``tenant_name`` attribute.  The canonical id for that
+  tenant is now ``0195f48b-d000-7000-8000-000000000001`` (see
+  ``the platform's Keycloak realm patch configmap``
+  ``TENANT_UUIDS``).
+* So the fallback pointed at the *stale label form* of a tenant that really
+  exists. Rows written under it land in a silo that no live JWT can ever
+  address, and reads under it silently cross out of whatever tenant the
+  operator believed the service was serving.
+
+Found live on ``coding-repo-jobs``, which sets no ``DEFAULT_TENANT_ID``:
+credential-less callers were reading, and could enqueue, against ``"n8n-dev"``.
+
+There is no safe literal to pick here. The value that would be "consistent"
+with coding-analysis / coding-security (``...0001``) is a *different* tenant
+from coding-repo-jobs' own ``WORKER_TENANT_ID`` (``...0003``), so any built-in
+default is a guess about someone else's data isolation. A missing tenant is
+therefore an error: unset means the credential-less paths refuse to mint a
+user at all, and — when a bypass is actually armed in production — the process
+refuses to boot.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from ._trusted_networks import load_trusted_networks
+
+logger = logging.getLogger(__name__)
+
+ENV_VAR = "DEFAULT_TENANT_ID"
+
+
+def load_default_tenant_id() -> str | None:
+    """Read ``DEFAULT_TENANT_ID`` from the environment. **No default value.**
+
+    An empty or whitespace-only value is treated the same as unset, mirroring
+    :meth:`coding_client.auth.models.User.model_post_init` — a blank tenant must
+    never pin a caller to an empty tenant.
+    """
+    return os.getenv(ENV_VAR, "").strip() or None
+
+
+DEFAULT_TENANT_ID: str | None = load_default_tenant_id()
+
+
+def resolve_default_tenant(purpose: str) -> str | None:
+    """Return the configured fallback tenant, or ``None`` — never a literal.
+
+    Callers MUST treat ``None`` as "reject this request". Substituting any
+    made-up value here is the bug this module exists to prevent.
+
+    Reads the module attribute at call time (not a captured copy) so tests can
+    monkeypatch it, matching :func:`._trusted_networks.is_trusted_network`.
+    """
+    tenant_id = DEFAULT_TENANT_ID
+    if tenant_id is None:
+        logger.error(
+            "%s is not configured; refusing to invent a tenant for %s. This "
+            "caller will be rejected. If this path is meant to be usable, set "
+            "%s on the Deployment env block to the tenant it should act as "
+            "(see the platform configuration policy).",
+            ENV_VAR,
+            purpose,
+            ENV_VAR,
+        )
+    return tenant_id
+
+
+def enforce_default_tenant_configured() -> None:
+    """Crash boot when a credential-less bypass is armed with no tenant to grant.
+
+    Follows the repo's fail-loud-in-production convention (see
+    :mod:`coding_client.config.base_settings`): a misconfiguration must be
+    visible at deploy time, not at 3am on one unlucky request.
+
+    The gate is deliberately narrow — it fires only when *all* of:
+
+    1. ``ENVIRONMENT`` is ``production`` (the default), and
+    2. ``TRUSTED_CIDRS`` is non-empty, i.e. an operator has armed the
+       credential-less network bypass, and
+    3. ``DEFAULT_TENANT_ID`` is unset.
+
+    Condition 2 is what keeps this from being a fleet-wide breaking change:
+    ``TRUSTED_CIDRS`` has been empty by default since 1.7.0, and no
+    ``coding-client`` consumer sets a non-empty one, so today this raises for
+    nobody. It exists so that *re-widening* ``TRUSTED_CIDRS`` without naming the
+    tenant fails the rollout instead of silently reviving the literal.
+
+    Raises:
+        RuntimeError: never ``ImportError`` — coding-security and coding-testing
+            wrap their auth-middleware import in ``except ImportError`` and log
+            "running WITHOUT authentication", so an ``ImportError`` here would be
+            swallowed into exactly the outcome this check is meant to prevent.
+    """
+    if os.getenv("ENVIRONMENT", "production") != "production":
+        return
+    trusted = load_trusted_networks()
+    if not trusted:
+        return
+    if load_default_tenant_id() is not None:
+        return
+    raise RuntimeError(
+        f"TRUSTED_CIDRS is set to {[str(n) for n in trusted]} — requests from "
+        f"those networks are admitted with NO credential — but {ENV_VAR} is not "
+        f"set, so there is no tenant to grant them. Refusing to start rather "
+        f"than serve a made-up tenant. Either set {ENV_VAR} on the Deployment "
+        f"env block, or clear TRUSTED_CIDRS to disable the bypass."
+    )
+
+
+enforce_default_tenant_configured()

coding_client/auth/_header_trust.py

@@ -0,0 +1,98 @@
+"""Whether client-supplied identity headers may be believed.
+
+``X-Tenant-Id`` (and its companions ``X-User-Id`` / ``X-User-Roles``) are
+*claims*, not credentials. Nothing in this library can verify them. Whether they
+are trustworthy is a property of the **network path**, not of the request:
+
+* Arriving through the mesh edge, they are trustworthy. The EnvoyFilter
+  ``ext-authz-enforce.yaml`` strips every client-supplied tenant header and
+  re-injects the value ``license-authz`` resolved from the license token, so by
+  the time the header reaches the pod it is an assertion by an authority.
+* Arriving pod-to-pod, they are **not** trustworthy. In-cluster callers do not
+  traverse the edge EnvoyFilter, so any workload that can open a socket to the
+  port can send ``X-Tenant-Id: <victim-tenant>`` and be served that tenant's
+  data. The header is accepted *above* license introspection in the precedence
+  chain, so a forged header wins over having no license at all.
+
+``TRUSTED_CIDRS`` does not address this. That knob governs the *no-header* case
+(:mod:`._trusted_networks`); emptying it does nothing to a request that carries
+a forged header, because such a request never reaches the network check.
+
+The knob
+--------
+``TRUST_TENANT_HEADER`` decides whether this process believes those headers.
+
+**The default is ``true`` — i.e. today's behaviour, which is the insecure one.**
+That is deliberate. This library is consumed by nine ``coding-*`` services with
+different exposure, and several of them legitimately depend on header trust
+(the gateway forwards ``X-Tenant-Id`` to backends that run with
+``ENABLE_AUTH=false`` and have no other way to learn the tenant). A default of
+``false`` would turn a routine lockfile refresh into a multi-service outage.
+So merging this changes nothing, and the security win lands per service, as
+each one sets ``TRUST_TENANT_HEADER=false`` on its Deployment once it is known
+to have a verifiable alternative (a license token, or the gateway in front).
+
+Setting it to ``false`` does **not** downgrade the caller to
+``DEFAULT_TENANT_ID``. The header is ignored as though absent and resolution
+continues down the normal chain — license introspection next. A request with a
+forged header and no valid license gets a 401, which is the point.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+#: Values that turn header trust OFF. Anything else leaves it ON.
+_DISABLE_VALUES = frozenset({"0", "false", "no", "off"})
+
+#: Values that explicitly turn header trust ON (accepted without complaint).
+_ENABLE_VALUES = frozenset({"1", "true", "yes", "on"})
+
+ENV_VAR = "TRUST_TENANT_HEADER"
+
+#: Behaviour when the variable is unset. ``True`` == today's behaviour.
+DEFAULT = True
+
+_warned_unrecognised: set[str] = set()
+
+
+def trust_tenant_header() -> bool:
+    """Return True if client-supplied identity headers may be believed.
+
+    Read from the environment at **call time**, not import time, so that a test
+    can flip it with ``monkeypatch.setenv`` and so the behaviour of a running
+    process is never pinned by import order.
+
+    An unrecognised value keeps the default (trusting). A typo must not silently
+    make a service *more* restrictive — that would present as an authentication
+    outage with no obvious cause. It is logged at ERROR instead, once per
+    distinct bad value.
+    """
+    raw = os.getenv(ENV_VAR)
+    if raw is None:
+        return DEFAULT
+
+    normalised = raw.strip().lower()
+    if not normalised:
+        # Set-but-empty is how a Deployment expresses "I did not decide".
+        # Treat it as unset rather than as a decision.
+        return DEFAULT
+    if normalised in _DISABLE_VALUES:
+        return False
+    if normalised in _ENABLE_VALUES:
+        return True
+
+    if raw not in _warned_unrecognised:
+        _warned_unrecognised.add(raw)
+        logger.error(
+            "%s=%r is not a recognised boolean; falling back to the default (%s). "
+            "Use one of %s to disable header trust.",
+            ENV_VAR,
+            raw,
+            DEFAULT,
+            sorted(_DISABLE_VALUES),
+        )
+    return DEFAULT

coding_client/auth/_onbehalf.py

@@ -0,0 +1,315 @@
+"""On-behalf-of vouching: who may assert a tenant that is not their own.
+
+A `coding-*` service that calls a sibling has, until now, had no way to say
+*"I am the containers service, and I am acting for customer T"*. Every outbound
+call carries a bare ``X-Tenant-Id`` and nothing else — a census of the fleet
+found **zero** sites forwarding an inbound ``Authorization``. So the only way a
+sibling call could succeed was through header trust, which is precisely the hole
+``TRUST_TENANT_HEADER=false`` exists to close. Flipping the gate without this
+module turns working service-to-service calls into 401s.
+
+Handing each service its own license does not solve it either: the tenant comes
+from the introspection body, so every S2S call would silently resolve to the
+*calling service's* tenant. That is a data-scoping bug wearing a fix's clothes.
+
+The mechanism
+-------------
+A caller presents its **own** service license in ``Authorization: Bearer`` and
+names the **customer** tenant in a plain ``X-Tenant-Id``. The asserted tenant is
+honoured only when the license introspects to a ``subject_id`` on this
+allowlist. This is the fleet-standard shape — ``kag_graph_service``,
+``graph_adapter_service``, ``kag`` and ``kag_orchestrator`` all run it, keyed on
+the same ``subject_id`` that ``licenses/scripts/provision_service_token.py``
+prints when it mints the credential.
+
+Unlike KAG — which copy-pastes the gate into seven services because they share
+no framework layer — every ``coding-*`` service consumes this one SDK, so the
+rule lives here once.
+
+Why the decision keys on DISAGREEMENT, not on the header's presence
+-------------------------------------------------------------------
+The obvious rule, "a plain ``X-Tenant-Id`` is honoured iff vouched, else 403",
+would break the entire north-south path. ``coding-gateway`` forwards the
+client's ``Authorization`` verbatim (its ``_HOP_BY_HOP`` list holds
+``proxy-authorization`` but **not** ``authorization``) *and* injects its own
+resolved ``x-tenant-id``. So every browser-originated request already arrives
+carrying both headers — the vouching shape, on the wire today, with nothing
+evaluating it. Under the naive rule the gateway's own injection would be
+indistinguishable from a forgery and every request behind it would 403.
+
+The tenant the gateway injects is the one it resolved from that same license, so
+it *agrees* with the token. Refusing only on disagreement keeps that path intact
+while still closing forgery:
+
+===========================  =========  ==========================================
+asserted vs token's tenant   vouched?   outcome
+===========================  =========  ==========================================
+absent                       --         token's tenant (unchanged behaviour)
+equal                        --         token's tenant (the gateway's own inject)
+differs                      yes        the **asserted** tenant — the grant
+differs                      no         **403** ``TENANT_ASSERTION_NOT_PERMITTED``
+===========================  =========  ==========================================
+
+Fail-closed, and the allowlist IS the rollout lever
+---------------------------------------------------
+Unset or empty vouches for nobody, which makes this module inert on install:
+with no allowlist, a differing assertion can only ever be refused, and today
+every such request is already refused by ``TRUST_TENANT_HEADER=false`` (or
+accepted wholesale when the gate is on, in which case this code is never
+reached). There is deliberately **no permissive spelling** — no wildcard, no
+"allow all", no escape-hatch variable. The fleet's own doctrine, written into
+the karma Deployment: *"an empty list is the fail-safe"*.
+
+That also makes this safer than the boolean it complements.
+``TRUST_TENANT_HEADER`` fails **open** on a typo — ``"flase"`` logs an error and
+keeps trusting. A typo in an allowlist entry can only ever fail to match.
+"""
+
+import logging
+import os
+import uuid
+
+from starlette.requests import HTTPConnection
+
+logger = logging.getLogger(__name__)
+
+#: Comma-separated ``subject_id``s permitted to assert a tenant that is not the
+#: one their own license names. The value is what
+#: ``licenses/scripts/provision_service_token.py`` prints as ``subject_id``.
+ENV_VAR = "CODING_ONBEHALF_SUBJECTS"
+
+#: Marker prefix the middleware synthesises for a license that names no subject
+#: (``license:<tenant_id>``). It is not a subject anyone was issued, so it must
+#: never be allowlistable — see :func:`onbehalf_subjects`.
+_SYNTHETIC_SUBJECT_PREFIX = "license:"
+
+_warned_synthetic: set[str] = set()
+
+
+def onbehalf_subjects() -> frozenset[str]:
+    """Parse the allowlist. Read at call time so tests and rollouts can move it.
+
+    Entries are stripped and blanks dropped, so trailing commas and wrapped YAML
+    are harmless.
+
+    🔴 A ``license:``-prefixed entry is **rejected**, loudly and every time.
+    When an active license carries no ``subject_id`` the middleware substitutes
+    the marker ``license:<tenant_id>`` so the blank never reaches the ``sub``
+    slot. That marker is shared by *every* subject-less license issued for that
+    tenant, so allowlisting one would hand the vouch to all of them at once —
+    the allowlist would stop naming a service and start naming a crowd. There is
+    no legitimate reason to list one, so this is a hard reject rather than a
+    warning: dropping the entry fails closed, honouring it fails open.
+    """
+    raw = os.getenv(ENV_VAR, "")
+    subjects: set[str] = set()
+
+    for entry in raw.split(","):
+        subject = entry.strip()
+        if not subject:
+            continue
+        if subject.startswith(_SYNTHETIC_SUBJECT_PREFIX):
+            if subject not in _warned_synthetic:
+                _warned_synthetic.add(subject)
+                logger.error(
+                    "%s contains the synthetic marker %r, which is not a real subject and "
+                    "is shared by every subject-less license for that tenant. Ignoring it. "
+                    "Use the subject_id printed by provision_service_token.py.",
+                    ENV_VAR,
+                    subject,
+                )
+            continue
+        subjects.add(subject)
+
+    return frozenset(subjects)
+
+
+def asserted_tenant(request: HTTPConnection) -> str:
+    """The tenant the caller is asking to act for, or ``""`` if none.
+
+    Read **ungated**. ``AuthMiddleware`` and ``require_tenant`` both null their
+    own ``x-tenant-id`` read when ``trust_tenant_header()`` is false; reusing
+    that value here would make vouching dead in exactly the deployment posture it
+    exists for.
+
+    A ``Bearer``-shaped value is treated as absent. Some fleet services overload
+    ``X-Tenant-Id`` to carry a credential (``coding-ai``'s worker-manager client
+    does), and binding a tenant literally named ``"Bearer"`` would be a smuggling
+    path. The split-on-whitespace form catches ``"Bearer  tok"`` and
+    ``"Bearer\\ttok"``, which a ``startswith("Bearer ")`` test does not.
+    """
+    raw = (request.headers.get("x-tenant-id") or "").strip()
+    if not raw:
+        return ""
+
+    parts = raw.split()
+    if parts and parts[0].lower() == "bearer":
+        return ""
+
+    return raw
+
+
+def may_vouch(subject_id: str | None) -> bool:
+    """True iff ``subject_id`` is allowlisted to act for another tenant.
+
+    Fail-closed at every exit: no subject, empty allowlist, synthetic marker, or
+    simply not listed.
+    """
+    if not subject_id:
+        return False
+    if subject_id.startswith(_SYNTHETIC_SUBJECT_PREFIX):
+        return False
+
+    subjects = onbehalf_subjects()
+    if not subjects:
+        return False
+
+    return subject_id in subjects
+
+
+#: Attributes this module writes onto ``request.state`` on EVERY path, so a
+#: reader can distinguish "the resolver ran and did not vouch" from "the
+#: resolver never ran". A reader that can only ever see the absence of an
+#: attribute cannot tell those apart, and a guard satisfied by a reader that
+#: never fires is not a guard.
+STATE_VOUCHED = "tenant_vouched"
+STATE_ASSERTED_TENANT = "asserted_tenant"
+STATE_VOUCHING_SUBJECT = "vouching_subject_id"
+STATE_LICENSE_ID = "license_id"
+
+
+def _record_not_vouched(request: HTTPConnection) -> None:
+    """Mark this request as *not* vouched. Called on both non-vouch exits."""
+    request.state.tenant_vouched = False
+
+
+def tenant_license_verified(request: HTTPConnection) -> bool:
+    """True iff this request's tenant was resolved from a **verified licence**.
+
+    False when it came from a trusted ``X-Tenant-Id`` header, from the
+    trusted-network bypass, or from nowhere at all — none of which reach
+    :func:`resolve_tenant_assertion`, which is why its absence is the signal.
+
+    🔴 This is the question a service must ask before lending its own credential
+    to an outbound call. ``coding-gateway`` presents its licence downstream so
+    the callee will honour the tenant it injects; if that tenant came from an
+    unverified header, the gateway is signing for a claim it never checked, and
+    the callee's allowlist — which exists to police exactly this — is satisfied
+    by the wrong party.
+
+    That is not hypothetical. Driven live on 2026-08-14: a forged, credential-less
+    ``x-tenant-id`` on a WebSocket upgrade to coding-gateway was accepted under
+    header trust, the gateway attached its own allowlisted licence, and
+    coding-analysis logged ``Vouched on-behalf-of: subject <svc-coding-gateway>
+    asserted tenant <someone else's>``. Any pod could read any tenant. The gate
+    below is what makes that impossible: with the tenant unverified, no
+    credential is lent, and the callee refuses as it should.
+    """
+    return getattr(request.state, STATE_VOUCHED, None) is not None
+
+
+def tenant_was_vouched(request: HTTPConnection) -> bool:
+    """True iff this request's tenant came from an on-behalf-of vouch.
+
+    The accessor exists so consumers do not hand-spell ``request.state``: a
+    renamed attribute then breaks in one place instead of silently reading
+    ``False`` forever at every call site. ``coding-gateway`` is the consumer —
+    it decides whether to forward the caller's credential or substitute its own.
+
+    **Defaults to False when the resolver never ran**, which is the safe answer:
+    no vouch happened, so nothing about the outbound credential should change.
+    That covers the header-trust, trusted-network and no-credential paths, none
+    of which reach :func:`resolve_tenant_assertion` at all.
+    """
+    return bool(getattr(request.state, STATE_VOUCHED, False))
+
+
+def resolve_tenant_assertion(
+    request: HTTPConnection, *, subject_id: str | None, token_tenant: str
+) -> tuple[str, bool]:
+    """Apply the disagreement rule. Returns ``(tenant_to_use, refused)``.
+
+    The single implementation of the table in this module's docstring. Both
+    :class:`~.middleware.AuthMiddleware` and :func:`~.tenant.require_tenant`
+    call it rather than each re-deriving the rule — the two have drifted before
+    (``TRUSTED_CIDRS`` and ``DEFAULT_TENANT_ID`` were once byte-identical copies,
+    and fixing one left the other permissive).
+
+    When ``refused`` is true the caller must reject with **403**, not 401: the
+    request is authenticated — the license is live and verified — it is simply
+    not authorised to speak for that tenant. A 401 would invite the caller to
+    retry with different credentials, which is not the problem.
+
+    Tenants are compared case-insensitively. The equal-case exists to recognise
+    ``coding-gateway`` re-injecting the tenant it resolved from this same token,
+    and a casing difference there would produce a false 403 on the entire
+    north-south path. It costs nothing: honouring a *differing* tenant still
+    requires the allowlist, so this only widens what counts as "the same tenant",
+    never who may change it.
+
+    The outcome is also RECORDED on ``request.state`` (see ``STATE_*`` above),
+    because a caller downstream of this decision has to act on it and cannot
+    re-derive it. ``coding-gateway`` is that caller: it forwards the client's own
+    credential when the tenant agreed, and substitutes its own when it had to
+    vouch — because on a vouched call the client's credential names a *different*
+    tenant than the one being asserted onward, which is precisely what the next
+    hop refuses. Recording it here rather than at each call site is the same
+    reason the rule itself lives here: ``AuthMiddleware``, ``require_tenant`` and
+    ``optional_tenant`` have drifted apart before.
+    """
+    asserted = asserted_tenant(request)
+    if not asserted or asserted.casefold() == token_tenant.casefold():
+        _record_not_vouched(request)
+        return token_tenant, False
+
+    if not may_vouch(subject_id):
+        logger.warning(
+            "Refusing tenant assertion: subject %r is not in %s and asserted a tenant "
+            "other than the one its license names (path=%s)",
+            subject_id,
+            ENV_VAR,
+            request.url.path,
+        )
+        _record_not_vouched(request)
+        return token_tenant, True
+
+    logger.info(
+        "Vouched on-behalf-of: subject %r asserted tenant %r (path=%s)",
+        subject_id,
+        asserted,
+        request.url.path,
+    )
+    request.state.tenant_vouched = True
+    request.state.asserted_tenant = asserted
+    # Audit trail, and the attribution a vouched call must carry onward: the
+    # CUSTOMER's license (forwarded by the caller), never the vouching service's
+    # own — otherwise every customer's spend bills to the service. Set here for
+    # all three resolvers; AuthMiddleware used to set these two itself, and
+    # require_tenant / optional_tenant did not, so a WebSocket route (which only
+    # ever runs require_tenant) had no attribution at all.
+    request.state.vouching_subject_id = subject_id
+    request.state.license_id = forwarded_license_id(request)
+    return asserted, False
+
+
+def forwarded_license_id(request: HTTPConnection) -> str | None:
+    """The customer's ``X-License-Id``, or ``None`` if absent/malformed.
+
+    On a vouched call the license that should be *attributed* is the customer's,
+    forwarded by the caller — never the vouching service's own, which would bill
+    every customer's spend to the service. Same rule as
+    ``kag_orchestrator``'s vouched branch.
+
+    Validated as a UUID and returned as the canonical string form, so a
+    caller-controlled header cannot inject an arbitrary value into a field that
+    downstream consumers treat as an identifier.
+    """
+    raw = (request.headers.get("x-license-id") or "").strip()
+    if not raw:
+        return None
+
+    try:
+        return str(uuid.UUID(raw))
+    except ValueError:
+        logger.warning("Ignoring malformed X-License-Id on a vouched request")
+        return None

coding_client/auth/_trusted_networks.py

@@ -0,0 +1,94 @@
+"""Trusted-network evaluation for the auth layer.
+
+``TRUSTED_CIDRS`` lets an operator nominate source networks whose requests are
+accepted **without any credential** and granted ``DEFAULT_TENANT_ID``. It is an
+authentication *bypass*, so its default is empty: a caller is trusted only when
+someone deliberately says so.
+
+Arming it takes two decisions, not one: *which* networks (here) and *which
+tenant* they then act as (``DEFAULT_TENANT_ID``, see :mod:`._default_tenant`,
+which has no default either and refuses to boot if this list is non-empty while
+it is unset).
+
+Why the default is empty (changed 2026-07-29)
+---------------------------------------------
+The previous default was
+``127.0.0.1/32,::1/128,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8``. On this fleet
+every pod carries an address in the k3s pod CIDR ``10.42.0.0/16``, which is a
+subset of ``10.0.0.0/8`` — so **every pod in the cluster** satisfied the bypass
+and was handed ``DEFAULT_TENANT_ID`` instead of a 401. That was demonstrated
+live: an unrelated pod in the ``artifacts`` namespace, with no Authorization
+header, no X-Tenant-Id and no license token, read
+``GET /api/containers/`` from coding-containers and got HTTP 200 with data.
+
+"The caller's IP looks local" is not authentication in a cluster where every
+workload is local. Legitimate in-mesh callers do not need this: coding-gateway
+strips client-supplied identity headers and re-injects ``x-tenant-id`` from the
+value it resolved itself (see ``coding-gateway`` ``routers/proxy.py``), so
+backends receive tenant context as a header from the gateway, and the mesh
+AuthorizationPolicy is what restricts who may reach the port at all.
+
+This module exists so the parsing lives in exactly one place. It previously
+existed as byte-identical copies in ``middleware.py`` and ``tenant.py``; a fix
+applied to one would silently have left the other permissive.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+_Network = ipaddress.IPv4Network | ipaddress.IPv6Network
+
+
+def _parse_cidrs(raw: str) -> list[_Network]:
+    """Parse a comma-separated CIDR list, skipping (and logging) bad entries.
+
+    A malformed entry must not take the whole list down to empty, because an
+    empty list is *more* restrictive and would turn a typo into an outage that
+    looks like an auth bug.
+    """
+    networks: list[_Network] = []
+    for chunk in raw.split(","):
+        cidr = chunk.strip()
+        if not cidr:
+            continue
+        try:
+            networks.append(ipaddress.ip_network(cidr, strict=False))
+        except ValueError:
+            logger.error("TRUSTED_CIDRS: ignoring unparseable entry %r", cidr)
+    return networks
+
+
+def load_trusted_networks() -> list[_Network]:
+    """Read ``TRUSTED_CIDRS`` from the environment. Empty by default."""
+    return _parse_cidrs(os.getenv("TRUSTED_CIDRS", ""))
+
+
+TRUSTED_NETWORKS: list[_Network] = load_trusted_networks()
+
+if TRUSTED_NETWORKS:
+    logger.warning(
+        "TRUSTED_CIDRS is set to %s — requests from these networks are accepted "
+        "with NO credential and granted DEFAULT_TENANT_ID. This is an "
+        "authentication bypass; confirm it is intended.",
+        [str(n) for n in TRUSTED_NETWORKS],
+    )
+
+
+def is_trusted_network(host: str | None) -> bool:
+    """True if *host* is a literal IP inside a configured trusted network.
+
+    Reads :data:`TRUSTED_NETWORKS` at call time (not a captured copy) so tests
+    can monkeypatch the module attribute.
+    """
+    if not host:
+        return False
+    try:
+        addr = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return any(addr in net for net in TRUSTED_NETWORKS)