kx-auth-core 0.5.0__py3-none-any.whl

kx_auth_core/__init__.py

@@ -0,0 +1,71 @@
+"""Lean, fastmcp-free shared core for kx auth.
+
+Holds the shared, fastmcp-free auth mechanisms imported by the container (``kx-mcp-core``), the
+backend bundles, and the client-side ``kx auth`` CLI alike:
+- **inbound** — the ``KX_MCP_AUTH`` config contract (:class:`AuthSettings`) + a joserfc-based
+  :func:`verify_token` (the one implementation of bearer validation; the container also keeps
+  FastMCP's ``JWTVerifier`` for serving);
+- **outbound** — the token-exchange seam (:func:`exchange` + :func:`register_outbound_strategy`),
+  so identity propagation is one implementation reused by every backend and the CLI.
+
+Deliberately depends on no fastmcp, so bundles and the CLI can use it without pulling in the server.
+"""
+
+from .assertion import project_from_claims, project_principal
+from .authz import (
+    ROUTE_ONLY_MODES,
+    AuthzAdapter,
+    AuthzDecision,
+    AuthzRequest,
+    authz_adapters,
+    decide,
+    register_authz_adapter,
+)
+from .outbound import (
+    OutboundConfig,
+    OutboundCredential,
+    decode_claims_unverified,
+    exchange,
+    outbound_strategies,
+    register_outbound_strategy,
+)
+from .settings import AuthSettings
+from .verify import (
+    AUTH_REQUIRED,
+    DENIED,
+    ERROR,
+    OK,
+    VerifyResult,
+    resolve_public_key,
+    verify_token,
+)
+
+__all__ = [
+    # inbound
+    "AuthSettings",
+    "verify_token",
+    "VerifyResult",
+    "resolve_public_key",
+    "OK",
+    "ERROR",
+    "AUTH_REQUIRED",
+    "DENIED",
+    # outbound
+    "exchange",
+    "register_outbound_strategy",
+    "outbound_strategies",
+    "OutboundConfig",
+    "OutboundCredential",
+    "decode_claims_unverified",
+    # identity assertion (plain kdb+)
+    "project_principal",
+    "project_from_claims",
+    # authorization decision seam
+    "AuthzRequest",
+    "AuthzDecision",
+    "AuthzAdapter",
+    "decide",
+    "register_authz_adapter",
+    "authz_adapters",
+    "ROUTE_ONLY_MODES",
+]

kx_auth_core/assertion.py

@@ -0,0 +1,110 @@
+"""Shape a validated principal into the dict ferried to kdb+ for identity assertion.
+
+Plain kdb+ has no bearer concept over qIPC, so the container does not mint a token for it (that's
+the ``outbound`` token-exchange seam used by OAuth backends such as KDB.AI). Instead it **asserts** the caller's
+identity: it ferries the validated structured fields + the raw claims to q, which calls
+``.kx.auth.bind[principal]``.
+
+**Promotion lives in q, not here.** ``.kx.auth.promote`` is the single authority that extracts
+``groups``/``tenant`` from the configured claim path, symbolises the promoted fields, and
+canonicalises ``exp`` — so the qIPC and HTTP transports converge on one promotion implementation.
+This helper only assembles the ferry shape: the structured fields q can't re-derive (``sub`` /
+``client`` / ``scopes`` / ``exp`` / ``aud`` / ``iss`` / ``act``) plus the raw ``claims`` blob q
+promotes from. It does not extract groups.
+
+It is deliberately:
+
+- **fastmcp-free** — operates on plain claim fields / a claims ``dict``, not fastmcp's
+  ``AccessToken``, so the container, the bundles, and the fastmcp-free ``kx auth`` CLI reuse one
+  implementation.
+- **pykx-free** — returns a plain Python ``dict``. The kdbx connection layer (which has PyKX) wraps
+  the raw ``claims`` string values as ``CharVector`` before sending, so high-cardinality values
+  (``jti`` …) do not intern as q symbols; q symbolises only the promoted fields.
+
+Two entry points, one implementation: :func:`project_principal` builds the ferry dict from
+already-extracted fields (what the kdbx connection layer has from ``current_principal()``);
+:func:`project_from_claims` builds it from a raw JWT claims dict (an indicative preview used by
+``kx auth assert --principal`` — the authoritative shape is whatever ``.kx.auth.promote`` produces).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+
+def _as_scope_list(scopes: Sequence[str] | str | None) -> list[str]:
+    """Normalise scopes to a list. Accepts a list or an OAuth space-delimited ``scope`` string."""
+    if scopes is None:
+        return []
+    if isinstance(scopes, str):
+        return scopes.split()
+    return [str(s) for s in scopes]
+
+
+def project_principal(
+    *,
+    subject: str | None,
+    client_id: str | None = None,
+    scopes: Sequence[str] | str | None = None,
+    expires_at: int | None = None,
+    audience: Any = None,
+    issuer: str | None = None,
+    act: Mapping[str, Any] | None = None,
+    claims: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Assemble the ferry dict from extracted fields.
+
+    The structured fields q cannot re-derive are passed through; ``aud`` / ``iss`` / ``act`` fall back
+    to the raw ``claims`` when not given explicitly. ``sub`` / ``client`` / ``scopes`` / ``claims`` are
+    always present so the q side can rely on their shape. **No groups/tenant extraction here** — q's
+    ``promote`` reads those from ``claims`` so qIPC and HTTP share one promotion path.
+    """
+    claims = dict(claims or {})
+    sub = subject or client_id or ""
+
+    if audience is None:
+        audience = claims.get("aud")
+    if issuer is None:
+        issuer = claims.get("iss")
+    if act is None:
+        act = claims.get("act")
+
+    out: dict[str, Any] = {
+        "sub": sub,
+        "client": client_id or "",
+        "scopes": _as_scope_list(scopes),
+        "claims": claims,
+    }
+    if audience is not None:
+        out["aud"] = audience
+    if issuer:
+        out["iss"] = issuer
+    if expires_at is not None:
+        out["exp"] = int(expires_at)
+    if act:
+        out["act"] = dict(act)
+    return out
+
+
+def project_from_claims(claims: Mapping[str, Any]) -> dict[str, Any]:
+    """Assemble the ferry dict from a raw JWT claims dict (the ``kx auth assert`` preview path).
+
+    Derives the structured fields (``sub`` / ``client`` / scopes / ``exp``) from the standard claim
+    names, then delegates to :func:`project_principal`. Groups are *not* derived here — they are q's
+    job (``.kx.auth.promote``), so this is an indicative preview of what gets ferried, not the final
+    promoted principal.
+    """
+    claims = dict(claims)
+    scope = claims.get("scope")
+    if scope is None:
+        scope = claims.get("scopes")
+    return project_principal(
+        subject=claims.get("sub"),
+        client_id=claims.get("client_id") or claims.get("azp"),
+        scopes=scope,
+        expires_at=claims.get("exp"),
+        audience=claims.get("aud"),
+        issuer=claims.get("iss"),
+        act=claims.get("act"),
+        claims=claims,
+    )

kx_auth_core/authz.py

@@ -0,0 +1,148 @@
+"""The pluggable authorization-decision seam.
+
+``decide(request, *, strategy)`` resolves ``strategy`` from a registry and runs the registered
+adapter, always returning an :class:`AuthzDecision` so the tool path reads ``allowed`` / ``reason`` /
+``obligations`` uniformly. A registry (not a hard-coded conditional) so a backend's capability
+adapter slots in via :func:`register_authz_adapter` without touching dispatch.
+Shaped like the outbound seam in :mod:`kx_auth_core.outbound.strategies`
+(``register_outbound_strategy`` / ``exchange`` / ``outbound_strategies``), so the codebase has one
+extension pattern, not two.
+
+This registry serves two kinds of check. A **capability check** sits at the tool boundary —
+data-agnostic, driven by the ``@authorize`` decorator (wired in :mod:`kx_mcp_core`), which builds an
+:class:`AuthzRequest` and calls :func:`decide`. An adapter can also do explicit-consult: call a
+backend's own data gate as a policy point and act on its verdict — the kdb-x entitlements adapter
+(``kdbx_entitlements``, consulting q ``.kx.auth.entitled`` in-tool on the bound handle) is the first
+of these. A backend whose data gate enforces directly on the data call itself (for example KDB.AI ACL)
+needs no adapter here. The bridge between the two check styles is :attr:`AuthzDecision.obligations`:
+a free-form scope-down payload (an entitled-symbol list, a where-clause fragment) an adapter uses to
+answer *allow-with-obligations* through the same boolean-first shape.
+
+Deliberately fastmcp-free. The ``action`` / ``resource`` vocabulary is a documented convention, not
+validated here (mirrors how the outbound seam never validates its audience/resource strings) — an
+adapter and the backend's own data gate must agree on the same strings by convention, not by code.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field, replace
+from typing import Any, Mapping, Optional, Protocol, Union, runtime_checkable
+
+# The strategy values that mean "no adapter — route-only allow" (the inbound `unset` precedent):
+# authorization is opt-in, so an unconfigured seam must not regress the zero-config posture.
+# Public: the container's `configure_authz` validates a configured mode against this, so the set of
+# modes that mean "no adapter, allow through" must have exactly one definition. Duplicating it in
+# kx-mcp-core would let the two drift silently, and a mode wrongly treated as route-only is an
+# allow-everything.
+ROUTE_ONLY_MODES = frozenset({"", "unset", "none"})
+
+
+@dataclass(frozen=True)
+class AuthzRequest:
+    """The question a capability check answers: may ``subject`` perform ``action`` on ``resource``?
+
+    ``action`` (e.g. ``query`` / ``write`` / ``search`` / ``admin``) and ``resource`` (e.g.
+    ``kdbx.sql`` / ``kdbai:table`` / ``acme:package``) are a documented convention, not validated —
+    both this adapter and the q ``authorize[action;resource]`` gate key on the same strings.
+    ``namespace`` is the mount namespace the primitive lives under (``kdbx`` / ``kdbai`` / ``acme``).
+    ``claims`` is the validated inbound principal's raw claims (an audit/escape-hatch payload;
+    adapters should prefer the promoted fields a backend exposes over re-deriving from raw claims).
+    """
+
+    subject: str
+    action: str
+    resource: str
+    namespace: str
+    claims: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AuthzDecision:
+    """The answer slip :func:`decide` always returns. Boolean-first; ``obligations`` is the optional
+    scope-down extension.
+
+    ``allowed`` is the decision. ``adapter`` records which registered adapter produced it (stamped by
+    :func:`decide`; ``None`` for the route-only allow). ``reason`` is a human/audit string. The
+    default-empty ``obligations`` is where an adapter expresses *allow-with-obligations* — a free-form
+    payload the tool/backend applies to scope a result down (e.g. an entitled-symbol list, a
+    where-clause fragment). Most adapters return a bare ``bool`` and never touch it.
+    """
+
+    allowed: bool
+    adapter: Optional[str] = None
+    reason: Optional[str] = None
+    obligations: Mapping[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class AuthzAdapter(Protocol):
+    """A capability adapter. Registered via :func:`register_authz_adapter` and dispatched by
+    :func:`decide`. Receives the :class:`AuthzRequest` and returns ``True`` / ``False`` for the common
+    case, or a full :class:`AuthzDecision` to carry ``reason`` / ``obligations``. **Raise to fail
+    closed** — :func:`decide` turns any exception into a deny, never an allow.
+    """
+
+    def __call__(self, request: AuthzRequest) -> Union[bool, AuthzDecision]: ...
+
+
+_ADAPTERS: dict[str, AuthzAdapter] = {}
+
+
+def register_authz_adapter(name: str, adapter: AuthzAdapter) -> None:
+    """Register an authorization adapter under ``name``. The extension point for a backend's
+    capability check. Mirrors ``register_outbound_strategy``."""
+    _ADAPTERS[name] = adapter
+
+
+def authz_adapters() -> list[str]:
+    """The names of all registered adapters, sorted. Mirrors ``outbound_strategies()`` / ``auth_modes()``."""
+    return sorted(_ADAPTERS)
+
+
+def decide(request: AuthzRequest, *, strategy: Optional[str]) -> AuthzDecision:
+    """Resolve ``strategy`` to an adapter, run it, and return an :class:`AuthzDecision`.
+
+    Three postures — the easy thing to get wrong, so they are explicit here:
+
+    * **route-only** — ``strategy`` is unset / ``"unset"`` / ``"none"`` (or ``None``): **allow**, with
+      ``adapter=None``. Authorization is opt-in; an unconfigured seam must not regress the zero-config
+      single-principal posture (the inbound ``KX_MCP_AUTH=unset`` precedent).
+    * **unknown strategy** — a *named* strategy not in the registry: ``ValueError`` (a clear operator
+      config error, surfaced loudly — mirrors ``exchange``'s unknown-strategy).
+    * **adapter raised** — a registered adapter throws at runtime: **deny / fail closed**
+      (``allowed=False``), the exception captured in ``reason``. An adapter exception must *never*
+      fall through to allow (matches the q-side ``policy:{[…] 0b}`` default).
+
+    A registered adapter returning a bare ``bool`` is normalised into an :class:`AuthzDecision`;
+    returning an :class:`AuthzDecision` is passed through with ``obligations`` intact. Either way the
+    producing ``adapter`` is stamped, so the caller reads one uniform shape.
+    """
+    if not strategy or strategy in ROUTE_ONLY_MODES:
+        return AuthzDecision(allowed=True, adapter=None, reason="no adapter configured (route-only)")
+
+    try:
+        adapter = _ADAPTERS[strategy]
+    except KeyError:
+        raise ValueError(
+            f"unknown authz strategy {strategy!r}; known: {authz_adapters()}"
+        ) from None
+
+    try:
+        result = adapter(request)
+    except Exception as exc:  # fail closed — an adapter error is a deny, never an allow
+        return AuthzDecision(
+            allowed=False, adapter=strategy, reason=f"adapter raised: {type(exc).__name__}: {exc}"
+        )
+
+    if isinstance(result, AuthzDecision):
+        # Pass the decision through (obligations intact), stamping the adapter when it didn't.
+        # Snapshot obligations on BOTH paths: `replace()` is a shallow copy, so the returned
+        # decision would otherwise share the adapter's own mapping object — an adapter that caches
+        # or extends its payload could mutate a decision a caller already holds (and already acted
+        # on). Deep because obligations nest (`{"entitled": [...], "denied": [...]}`), so a
+        # top-level copy would still share the lists. The self-stamped path needs it too: that one
+        # skips `replace` entirely and was the aliasing case a `replace`-only fix left behind.
+        stamped = result if result.adapter else replace(result, adapter=strategy)
+        return replace(stamped, obligations=deepcopy(stamped.obligations))
+    return AuthzDecision(allowed=bool(result), adapter=strategy)

kx_auth_core/outbound/__init__.py

@@ -0,0 +1,21 @@
+"""Outbound identity propagation: the pluggable token-exchange seam.
+
+A backend tool reads the validated inbound principal (`current_principal()`) and calls
+`exchange(config, subject_token)` to mint the backend-shaped credential — `passthrough` / `rfc_8693`
+/ `service_account`, or a `custom` driver registered via `register_outbound_strategy`. The exchange
+runs in the tool, not in parent middleware (the principal crosses the mount boundary; middleware
+state does not).
+"""
+
+from .claims import decode_claims_unverified
+from .config import OutboundConfig, OutboundCredential
+from .strategies import exchange, outbound_strategies, register_outbound_strategy
+
+__all__ = [
+    "OutboundConfig",
+    "OutboundCredential",
+    "exchange",
+    "register_outbound_strategy",
+    "outbound_strategies",
+    "decode_claims_unverified",
+]

kx_auth_core/outbound/claims.py

@@ -0,0 +1,26 @@
+"""Best-effort JWT claim decode for **audit / traceability only** — never for authorization.
+
+The container does not re-verify tokens it mints/forwards outbound: a `passthrough` token was already
+validated inbound, and an `rfc_8693` / `service_account` token came straight from a just-called
+trusted STS. We decode the payload only to record `sub` / `aud` / `jti` / `scope` in the audit chain.
+Opaque (non-JWT) tokens decode to ``{}`` — the credential still works, it just carries no claims.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+
+def decode_claims_unverified(token: str | None) -> dict[str, Any]:
+    """Decode a JWT's payload without signature verification. ``{}`` for opaque/empty tokens."""
+    if not token:
+        return {}
+    try:
+        payload_b64 = token.split(".")[1]
+        padded = payload_b64 + "=" * (-len(payload_b64) % 4)
+        decoded = json.loads(base64.urlsafe_b64decode(padded))
+    except Exception:
+        return {}
+    return decoded if isinstance(decoded, dict) else {}

kx_auth_core/outbound/config.py

@@ -0,0 +1,139 @@
+"""Outbound identity-propagation config + the credential it produces.
+
+`OutboundConfig` is a backend's outbound fragment — constructed by the extension from *its own* env
+prefix (`KDBAI_OUTBOUND_*`, `KXI_OUTBOUND_*`, …); the container owns the schema + the strategies, the
+extension owns *which* strategy and *which* endpoint. Frozen, so it can key a per-principal connection
+cache.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+# RFC 8693 / OAuth constants (the wire shape `rfc_8693` sends).
+GRANT_TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange"
+GRANT_CLIENT_CREDENTIALS = "client_credentials"
+TOKEN_TYPE_ACCESS = "urn:ietf:params:oauth:token-type:access_token"
+
+
+class OutboundConfig(BaseModel):
+    """How a backend propagates the inbound principal outbound (frozen).
+
+    The public contract for outbound identity propagation: a backend builds this from its own
+    env-prefixed fragment and hands it to :func:`exchange`. The per-field descriptions are the
+    canonical reference for what each knob does and which strategy consults it.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    strategy: str = Field(
+        default="passthrough",
+        description=(
+            "Which outbound strategy to run. Resolved by name from the register_outbound_strategy "
+            "registry at exchange() time (a bare str, not an enum, so custom drivers register "
+            "arbitrary names — mirrors the inbound KX_MCP_AUTH mode). Built-ins: passthrough / "
+            "rfc_8693 / service_account. An unregistered name raises ValueError at exchange()."
+        ),
+    )
+    token_url: Optional[str] = Field(
+        default=None,
+        description=(
+            "OIDC/STS token endpoint. Required by rfc_8693 and service_account; unused by passthrough."
+        ),
+    )
+    audience: Optional[str] = Field(
+        default=None,
+        description=(
+            "Target backend audience. rfc_8693 requests a token for it; passthrough's guard refuses "
+            "unless the inbound token's aud already includes it; service_account may request it."
+        ),
+    )
+    resource: Optional[str] = Field(
+        default=None,
+        description="Optional RFC 8707 resource URI — an alternative to audience for rfc_8693.",
+    )
+    client_id: Optional[str] = Field(
+        default=None,
+        description=(
+            "Client identity for authenticating at the token endpoint (rfc_8693 / service_account)."
+        ),
+    )
+    client_secret: Optional[SecretStr] = Field(
+        default=None,
+        description="Client secret paired with client_id. SecretStr — kept out of logs and reprs.",
+    )
+    client_auth: Literal["basic", "post"] = Field(
+        default="post",
+        description=(
+            "How credentials reach the token endpoint (RFC 6749 §2.3): 'post' = in the request body "
+            "(client_secret_post), 'basic' = Authorization: Basic header (client_secret_basic). "
+            "Default 'post' matches the supported backend IdPs. Only "
+            "consulted when client_id is set."
+        ),
+    )
+    scopes: Optional[list[str]] = Field(
+        default=None,
+        description=(
+            "Optional requested scopes, space-joined onto the token request "
+            "(rfc_8693 / service_account)."
+        ),
+    )
+    subject_token_type: str = Field(
+        default=TOKEN_TYPE_ACCESS,
+        description=(
+            "RFC 8693 subject_token_type for the inbound bearer. Defaults to an OAuth access token."
+        ),
+    )
+    verify: bool = Field(
+        default=True,
+        description=(
+            "TLS verification for the token call exchange() makes when it builds its own client "
+            "(ignored if the caller passes its own client). Set False for e.g. a self-signed dev "
+            "Keycloak — without the backend importing httpx."
+        ),
+    )
+    timeout: float = Field(
+        default=30.0,
+        description=(
+            "Request timeout (seconds) for that same token call; ignored when the caller passes a "
+            "client."
+        ),
+    )
+
+
+class OutboundCredential(BaseModel):
+    """The product of an exchange: the credential to present to the backend, plus audit metadata."""
+
+    access_token: str = Field(
+        description=(
+            "The credential to present to the backend (forwarded as-is by passthrough; minted by "
+            "rfc_8693 / service_account)."
+        ),
+    )
+    token_type: str = Field(
+        default="Bearer",
+        description=(
+            "OAuth token type from the token endpoint; 'Bearer' for passthrough and the usual "
+            "default otherwise."
+        ),
+    )
+    expires_in: Optional[int] = Field(
+        default=None,
+        description=(
+            "Lifetime in seconds as reported by the token endpoint; None for passthrough (the "
+            "forwarded token carries its own expiry)."
+        ),
+    )
+    strategy: str = Field(
+        default="",
+        description="The strategy that produced this credential — recorded in the audit chain.",
+    )
+    claims: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Best-effort, *unverified* decode of access_token (sub / aud / jti / scope), for the "
+            "audit chain ONLY — never an authorization input. {} for opaque (non-JWT) tokens."
+        ),
+    )

kx_auth_core/outbound/strategies.py

@@ -0,0 +1,225 @@
+"""The pluggable outbound token-exchange seam.
+
+`exchange(config, subject_token)` resolves `config.strategy` from a registry and runs it, returning
+an `OutboundCredential` for the backend. A registry (not a hard-coded conditional) so a `custom`
+driver — e.g. Microsoft Entra OBO — slots in via `register_outbound_strategy` without touching
+dispatch. Mirrors the inbound verifier seam in `auth/providers.py`. Built-in strategies: `passthrough`
+(forward the inbound bearer when its audience matches), `rfc_8693` (RFC 8693 token exchange), and
+`service_account` (`client_credentials` — the container's own workload identity).
+
+Each exchange emits one `kx_mcp.audit` line so the inbound→exchange→outbound chain is traceable.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional, Protocol
+
+import httpx
+
+from .claims import decode_claims_unverified
+from .config import (
+    GRANT_CLIENT_CREDENTIALS,
+    GRANT_TOKEN_EXCHANGE,
+    OutboundConfig,
+    OutboundCredential,
+)
+
+logger = logging.getLogger("kx_mcp.audit")
+
+
+class OutboundStrategy(Protocol):
+    """A custom outbound driver. Registered via ``register_outbound_strategy`` and dispatched by
+    ``exchange``. Receives the backend's ``OutboundConfig`` and the inbound bearer (``None`` for
+    workload strategies like ``service_account``), plus a keyword-only pooled ``httpx.AsyncClient``
+    to reuse. Returns the credential to present to the backend. Raise ``ValueError`` on missing
+    config, ``PermissionError`` to refuse (e.g. an audience guard).
+    """
+
+    async def __call__(
+        self, config: OutboundConfig, subject_token: Optional[str], *, client: httpx.AsyncClient
+    ) -> OutboundCredential: ...
+
+
+_STRATEGIES: dict[str, OutboundStrategy] = {}
+
+
+def register_outbound_strategy(name: str, strategy: OutboundStrategy) -> None:
+    """Register an outbound strategy. The extension point for `custom` drivers."""
+    _STRATEGIES[name] = strategy
+
+
+def outbound_strategies() -> list[str]:
+    """The names of all registered strategies (built-ins + custom), sorted. Mirrors ``auth_modes()``."""
+    return sorted(_STRATEGIES)
+
+
+async def exchange(
+    config: OutboundConfig,
+    subject_token: Optional[str] = None,
+    *,
+    client: Optional[httpx.AsyncClient] = None,
+) -> OutboundCredential:
+    """Run the configured outbound strategy and return the backend credential.
+
+    Pass an `httpx.AsyncClient` to reuse a pooled client; otherwise one is created and closed per
+    call. Raises `ValueError` on an unknown strategy or missing required config; `PermissionError`
+    when `passthrough`'s audience guard refuses.
+
+    Emits one `kx_mcp.audit` record per call (the inbound→exchange→outbound chain), on success and
+    failure alike.
+    """
+    try:
+        strategy = _STRATEGIES[config.strategy]
+    except KeyError:
+        raise ValueError(
+            f"unknown outbound strategy {config.strategy!r}; known: {outbound_strategies()}"
+        ) from None
+
+    owns_client = client is None
+    client = client or httpx.AsyncClient(verify=config.verify, timeout=config.timeout)
+    try:
+        credential = await strategy(config, subject_token, client=client)
+    except Exception as exc:
+        _audit(config, subject_token, credential=None, error=exc)
+        raise
+    finally:
+        if owns_client:
+            await client.aclose()
+
+    _audit(config, subject_token, credential=credential, error=None)
+    return credential
+
+
+# --- built-in strategies -----------------------------------------------------------------------
+
+
+async def _passthrough(
+    config: OutboundConfig, subject_token: Optional[str], *, client: httpx.AsyncClient
+) -> OutboundCredential:
+    """Forward the inbound bearer unchanged — only when its audience matches the configured backend.
+
+    ``audience`` is **required**: forwarding a bearer without checking it was minted for this backend
+    is a confused-deputy risk, so an unset audience is *refused* rather than blindly forwarded.
+    """
+    if not subject_token:
+        raise ValueError("passthrough requires an inbound subject token (none present)")
+    if not config.audience:
+        raise ValueError(
+            "passthrough requires `audience` — refusing to forward a bearer without verifying it "
+            "was minted for this backend (confused-deputy guard)"
+        )
+    claims = decode_claims_unverified(subject_token)
+    if not _audience_includes(claims.get("aud"), config.audience):
+        raise PermissionError(
+            f"passthrough refused: inbound audience {claims.get('aud')!r} "
+            f"does not include {config.audience!r}"
+        )
+    return OutboundCredential(access_token=subject_token, strategy="passthrough", claims=claims)
+
+
+async def _rfc_8693(
+    config: OutboundConfig, subject_token: Optional[str], *, client: httpx.AsyncClient
+) -> OutboundCredential:
+    """RFC 8693 token exchange: swap the inbound bearer for a backend-audience token."""
+    if not subject_token:
+        raise ValueError("rfc_8693 requires an inbound subject token (none present)")
+    if not config.token_url:
+        raise ValueError("rfc_8693 requires token_url")
+    data = {
+        "grant_type": GRANT_TOKEN_EXCHANGE,
+        "subject_token": subject_token,
+        "subject_token_type": config.subject_token_type,
+    }
+    if config.audience:
+        data["audience"] = config.audience
+    if config.resource:
+        data["resource"] = config.resource
+    if config.scopes:
+        data["scope"] = " ".join(config.scopes)
+    return await _post_for_token(config, data, client, strategy="rfc_8693")
+
+
+async def _service_account(
+    config: OutboundConfig, subject_token: Optional[str], *, client: httpx.AsyncClient
+) -> OutboundCredential:
+    """OAuth client_credentials — the container's own workload identity, not the caller's."""
+    if not config.token_url:
+        raise ValueError("service_account requires token_url")
+    data = {"grant_type": GRANT_CLIENT_CREDENTIALS}
+    if config.audience:
+        data["audience"] = config.audience
+    if config.scopes:
+        data["scope"] = " ".join(config.scopes)
+    return await _post_for_token(config, data, client, strategy="service_account")
+
+
+async def _post_for_token(
+    config: OutboundConfig, data: dict[str, str], client: httpx.AsyncClient, *, strategy: str
+) -> OutboundCredential:
+    url = config.token_url
+    assert url is not None  # callers guard this; narrows Optional[str] for the type checker
+    headers = {"Accept": "application/json"}
+    body = dict(data)  # copy — don't mutate the caller's dict when adding post-body creds
+    auth: Optional[tuple[str, str]] = None
+    if config.client_id:
+        secret = config.client_secret.get_secret_value() if config.client_secret else ""
+        if config.client_auth == "basic":
+            auth = (config.client_id, secret)  # client_secret_basic — Authorization header
+        else:
+            body["client_id"] = config.client_id  # client_secret_post — credentials in the body
+            body["client_secret"] = secret
+    if auth is not None:
+        response = await client.post(url, data=body, headers=headers, auth=auth)
+    else:
+        response = await client.post(url, data=body, headers=headers)
+    response.raise_for_status()
+    body = response.json()
+    token = body.get("access_token")
+    if not token:
+        raise ValueError(f"{strategy}: token endpoint returned no access_token")
+    return OutboundCredential(
+        access_token=token,
+        token_type=body.get("token_type", "Bearer"),
+        expires_in=body.get("expires_in"),
+        strategy=strategy,
+        claims=decode_claims_unverified(token),
+    )
+
+
+def _audience_includes(aud: object, wanted: str) -> bool:
+    if aud is None:
+        return False
+    audiences = aud if isinstance(aud, list) else [aud]
+    return wanted in audiences
+
+
+def _audit(
+    config: OutboundConfig,
+    subject_token: Optional[str],
+    *,
+    credential: Optional[OutboundCredential],
+    error: Optional[Exception],
+) -> None:
+    subject = decode_claims_unverified(subject_token).get("sub") or "anonymous"
+    if error is not None:
+        logger.info(
+            "audit exchange strategy=%s subject=%s -> audience=%s outcome=error error=%s",
+            config.strategy, subject, config.audience, type(error).__name__,
+        )
+        return
+    assert credential is not None
+    claims = credential.claims
+    logger.info(
+        "audit exchange strategy=%s subject=%s -> audience=%s jti=%s scopes=%s outcome=ok",
+        credential.strategy or config.strategy,
+        subject,
+        config.audience or claims.get("aud"),
+        claims.get("jti"),
+        claims.get("scope"),
+    )
+
+
+register_outbound_strategy("passthrough", _passthrough)
+register_outbound_strategy("rfc_8693", _rfc_8693)
+register_outbound_strategy("service_account", _service_account)

kx_auth_core/settings.py

@@ -0,0 +1,105 @@
+"""Container inbound-auth configuration (the ``KX_MCP_AUTH`` family) — the shared config contract.
+
+The *mode* lives in the bare ``KX_MCP_AUTH`` env var (``unset`` / ``static`` / ``jwks`` /
+``oidc_proxy`` / ``entra``; later ``proxy_headers`` — see the verifier seam in
+:mod:`kx_mcp_core.auth.providers`); the mode-specific detail lives under the ``KX_MCP_AUTH_*``
+prefix. This is the container's config fragment — distinct from each extension's own prefix
+(``KDBX_DB_*``, ``KDBAI_DB_*``).
+
+This model lives in the lean ``kx-auth-core`` package (no fastmcp) so **both** the container and the
+client-side ``kx auth`` CLI bind to the *same* config: the CLI validates a bearer against the same
+keys/issuer/audience the container enforces. ``kx_mcp_core.auth.AuthSettings`` re-exports it.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import AliasChoices, Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AuthSettings(BaseSettings):
+    """Resolved inbound-auth config. Read from the environment by default; constructible by name
+    in tests/glue (``AuthSettings(mode="static", public_key=...)``)."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="KX_MCP_AUTH_",
+        populate_by_name=True,
+        extra="ignore",
+    )
+
+    # The mode selector is the bare KX_MCP_AUTH var (not KX_MCP_AUTH_MODE) — see the module docstring.
+    mode: str = Field(default="unset", validation_alias="KX_MCP_AUTH")
+
+    # static (RS256 against a local public key) — supply the PEM inline or by path.
+    public_key: Optional[str] = None
+    public_key_path: Optional[str] = None
+
+    # jwks (RS256 against a remote JWKS endpoint — Keycloak / Auth0 / any OIDC issuer).
+    jwks_uri: Optional[str] = None
+
+    # The container's own public base URL, as clients reach it (e.g. https://mcp.example or
+    # http://127.0.0.1:8000). When set, the jwks provider advertises RFC 9728 Protected Resource
+    # Metadata (the issuer as authorization_server) so an MCP client / `kx auth login` can *discover*
+    # the IdP from the server. Unset → the verifier validates only (no discovery) — correct for the
+    # stdio / no-public-URL posture. Must equal the URL the client actually connects to (proxy-aware).
+    resource_url: Optional[str] = None
+
+    # Shared claim-validation knobs for static + jwks.
+    issuer: Optional[str] = None
+    audience: Optional[str] = None
+    algorithm: str = "RS256"
+    required_scopes: Optional[List[str]] = None
+
+    # entra (FastMCP's AzureProvider — the OAuth-Proxy front door for clients that must *log in*
+    # against Microsoft Entra, which has no open DCR). These name the **one app you pre-register**;
+    # the proxy brokers the flow on its behalf. `base_url` is the container's public URL (reuse
+    # `resource_url`). We accept both the canonical `KX_MCP_AUTH_*` names and the `AZURE_*` names
+    # the Azure tooling / FastMCP docs use, so an existing Azure-app `.env` works unchanged.
+    client_id: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("KX_MCP_AUTH_CLIENT_ID", "AZURE_CLIENT_ID"),
+    )
+    client_secret: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("KX_MCP_AUTH_CLIENT_SECRET", "AZURE_CLIENT_SECRET"),
+    )
+    tenant_id: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("KX_MCP_AUTH_TENANT_ID", "AZURE_TENANT_ID"),
+    )
+    # Application ID URI exposed by the app registration; defaults to api://{client_id} in Entra,
+    # so leave unset unless you configured a custom one.
+    identifier_uri: Optional[str] = None
+
+    # oidc_proxy (FastMCP's OIDCProxy — `entra` generalised to any OIDC issuer whose DCR is
+    # closed). Reuses `client_id`/`client_secret` (the one app you pre-register), `resource_url`
+    # (base_url), `audience`, `algorithm` and `required_scopes`.
+
+    # The discovery document. Derived as `{issuer}/.well-known/openid-configuration` when unset;
+    # set it for issuers that serve it elsewhere (Entra v2.0, some Auth0/Okta setups).
+    config_url: Optional[str] = None
+    # Signs container-issued tokens and keys the encrypted OAuth-state store. Unset → both are
+    # derived from `client_secret`. Required for a public/PKCE client with no secret.
+    jwt_signing_key: Optional[str] = None
+    # False accepts a discovery document missing an OIDC-required field (usually
+    # `subject_types_supported`).
+    oidc_strict: bool = True
+
+    @field_validator("mode", mode="before")
+    @classmethod
+    def _normalise_mode(cls, value: object) -> str:
+        """Empty / whitespace / unset all collapse to ``unset`` (the no-auth bundling posture)."""
+        if isinstance(value, str) and value.strip():
+            return value.strip().lower()
+        return "unset"
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _split_scopes(cls, value: object) -> object:
+        """Accept a comma- or space-separated string from the environment (not just JSON)."""
+        if isinstance(value, str):
+            parts = value.replace(",", " ").split()
+            return parts or None
+        return value

kx_auth_core/verify.py

@@ -0,0 +1,240 @@
+"""The shared, fastmcp-free JWT verifier — one implementation, two front doors.
+
+``verify_token(token, settings)`` decodes and validates a bearer against the same ``KX_MCP_AUTH``
+config the container enforces, using **joserfc** (the exact JOSE library FastMCP's ``JWTVerifier``
+uses under the hood) so the CLI's verdict matches what the container would do. The serving path
+(``kx_mcp_core.auth.providers``) keeps FastMCP's ``JWTVerifier`` — this is the *same* validation
+logic, mirrored; the repo's ``test_auth_cli_contract`` pins the two in agreement.
+
+Unlike the FastMCP verifier (which collapses every failure to ``None``), this returns a
+**categorised** :class:`VerifyResult` so the ``kx auth introspect`` CLI can map to its stable
+exit-code contract:
+
+* ``OK``            — valid, accepted                                  (exit 0 / HTTP 200)
+* ``ERROR``         — malformed token, bad signature, unreachable/bad JWKS  (exit 1 / HTTP 400/500)
+* ``AUTH_REQUIRED`` — well-signed but expired; the agent should re-login   (exit 3 / HTTP 401)
+* ``DENIED``        — well-signed but not acceptable here: issuer / audience / required-scope
+                      mismatch                                          (exit 4 / HTTP 403)
+
+The static-vs-denied split mirrors HTTP 401/403: a structurally broken token is an ``ERROR``; a
+genuine, properly-signed token that simply isn't authorised for this resource is ``DENIED``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+from joserfc import jwk, jwt
+from joserfc.errors import JoseError
+
+from .settings import AuthSettings
+
+# Verdict categories (stable; the CLI maps these to exit codes).
+OK = "ok"
+ERROR = "error"
+AUTH_REQUIRED = "auth_required"
+DENIED = "denied"
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    """The categorised outcome of verifying a bearer. ``valid`` is true only for :data:`OK`."""
+
+    category: str
+    valid: bool
+    claims: Optional[dict] = None
+    client_id: Optional[str] = None
+    scopes: Optional[list] = None
+    reason: Optional[str] = None
+
+    @classmethod
+    def ok(cls, claims: dict, client_id: str, scopes: list) -> "VerifyResult":
+        return cls(OK, True, claims=claims, client_id=client_id, scopes=scopes)
+
+    @classmethod
+    def fail(cls, category: str, reason: str) -> "VerifyResult":
+        return cls(category, False, reason=reason)
+
+
+def resolve_public_key(settings: AuthSettings) -> str:
+    """Resolve the static-mode public-key PEM (inline or by path). Shared with the container's
+    ``_build_static`` so both read the key identically."""
+    if settings.public_key:
+        return settings.public_key
+    if settings.public_key_path:
+        return Path(settings.public_key_path).read_text()
+    raise ValueError(
+        "KX_MCP_AUTH=static requires KX_MCP_AUTH_PUBLIC_KEY or KX_MCP_AUTH_PUBLIC_KEY_PATH "
+        "(an RS256 public-key PEM)"
+    )
+
+
+def _import_key(key: str | bytes | dict, algorithm: str):
+    """Import key material for the algorithm family (mirrors FastMCP's ``_import_key_for_algorithm``)."""
+    if algorithm.startswith("HS"):
+        return jwk.import_key(key, "oct")
+    if algorithm.startswith(("RS", "PS")):
+        return jwk.import_key(key, "RSA")
+    if algorithm.startswith("ES"):
+        return jwk.import_key(key, "EC")
+    raise ValueError(f"Unsupported algorithm: {algorithm}.")
+
+
+def _jwk_to_pem(key_data: dict) -> str:
+    kty = key_data.get("kty")
+    if kty == "RSA":
+        return jwk.import_key(key_data, "RSA").as_pem().decode("utf-8")
+    if kty == "EC":
+        return jwk.import_key(key_data, "EC").as_pem().decode("utf-8")
+    raise ValueError(f"Unsupported JWK key type: {kty!r}")
+
+
+def _decode_header(token: str) -> dict:
+    """Decode a JWT's header segment without verifying — used only to read ``kid`` for JWKS lookup."""
+    try:
+        header_b64 = token.split(".")[0]
+        padded = header_b64 + "=" * (-len(header_b64) % 4)
+        return json.loads(base64.urlsafe_b64decode(padded))
+    except Exception as exc:  # malformed token — caller surfaces as ERROR
+        raise ValueError(f"could not decode token header: {exc}") from exc
+
+
+def _resolve_jwks_key(settings: AuthSettings, token: str) -> str:
+    """Fetch the JWKS and return the PEM for the token's ``kid`` (or the sole key)."""
+    if not settings.jwks_uri:
+        raise ValueError("KX_MCP_AUTH=jwks requires KX_MCP_AUTH_JWKS_URI (the issuer's JWKS endpoint)")
+    kid = _decode_header(token).get("kid")
+    resp = httpx.get(settings.jwks_uri, timeout=10.0)
+    resp.raise_for_status()
+    # A LIST of (kid, pem) pairs, not a dict keyed on kid: two entries sharing a kid — or, the case
+    # that actually bit, two entries with NO kid at all, which both used to collapse onto one
+    # "_default" slot — silently reduced the key count, turning a genuine "multiple keys, no kid"
+    # ambiguity into a single-key selection whose outcome depended on the order the issuer happened
+    # to serve its JWKS in. Ambiguity must be an error, and the same error either way.
+    entries = [(key_data.get("kid"), _jwk_to_pem(key_data)) for key_data in resp.json().get("keys", [])]
+    if not entries:
+        raise ValueError("no keys found in JWKS")
+    if kid:
+        matches = [pem for entry_kid, pem in entries if entry_kid == kid]
+        if not matches:
+            raise ValueError(f"key ID {kid!r} not found in JWKS")
+        if len(matches) > 1:
+            raise ValueError(f"multiple keys in JWKS share key ID (kid) {kid!r}")
+        return matches[0]
+    if len(entries) == 1:
+        return entries[0][1]
+    raise ValueError("multiple keys in JWKS but no key ID (kid) in token")
+
+
+def _extract_scopes(claims: dict) -> tuple[list, str]:
+    """Scopes from the standard ``scope`` claim, falling back to ``scp``. Mirrors FastMCP.
+
+    Returns ``(scopes, status)`` where status is one of:
+
+    * ``"ok"`` — a well-formed claim, or none at all.
+    * ``"invalid_members"`` — a **list**-valued claim carrying a non-string member. FastMCP's
+      ``JWTVerifier`` **rejects** this token outright (``AccessToken.scopes`` is typed
+      ``list[str]``), verified live against the pinned fastmcp, so the caller must too — anything
+      else and ``kx auth introspect`` would report a verdict the container does not enforce.
+      Rejecting also means an *unhashable* member never reaches the caller's ``set(scopes)``, which
+      is evaluated outside the try/except and used to escape as a bare ``TypeError``.
+    * ``"malformed_type"`` — the claim is present but is neither a string nor a list. ``JWTVerifier``
+      **accepts** this, treating it as no scope, so the token stays valid here as well; the status
+      exists only so the caller's reason can distinguish "carried a broken claim" from "carried no
+      claim", which used to read identically.
+
+    The ``scope`` → ``scp`` fall-through is preserved: a wrong-typed ``scope`` still lets a
+    well-formed ``scp`` win, it just remembers the first claim was broken.
+
+    Both verdicts are pinned by ``tests/deterministic/unit/test_auth_cli_contract.py``, which now
+    parametrizes the hostile shapes — it previously only fed well-formed claims, so this function
+    was free to drift from the verifier it is meant to mirror.
+    """
+    status = "ok"
+    for claim in ("scope", "scp"):
+        if claim not in claims:
+            continue
+        value = claims[claim]
+        if isinstance(value, str):
+            return value.split(), status
+        if isinstance(value, list):
+            if not all(isinstance(member, str) for member in value):
+                return [], "invalid_members"
+            return value, status
+        status = "malformed_type"
+    return [], status
+
+
+def _audience_ok(expected: Any, actual: Any) -> bool:
+    expected_list = expected if isinstance(expected, list) else [expected]
+    actual_list = actual if isinstance(actual, list) else [actual]
+    return any(e in actual_list for e in expected_list)
+
+
+def verify_token(token: str, settings: AuthSettings) -> VerifyResult:
+    """Verify ``token`` against ``settings`` and return a categorised :class:`VerifyResult`.
+
+    Signature failures / malformed tokens / JWKS problems are :data:`ERROR`; a well-signed but
+    expired token is :data:`AUTH_REQUIRED`; a well-signed token failing issuer / audience /
+    required-scope checks is :data:`DENIED`. The validation order mirrors FastMCP's ``JWTVerifier``.
+    """
+    if settings.mode not in ("static", "jwks"):
+        return VerifyResult.fail(
+            ERROR, f"introspect requires KX_MCP_AUTH=static or jwks (got {settings.mode!r})"
+        )
+
+    # 1. Resolve the verification key, then verify the signature (joserfc raises on bad sig/format).
+    try:
+        if settings.mode == "static":
+            verification_key = resolve_public_key(settings)
+        else:
+            verification_key = _resolve_jwks_key(settings, token)
+        key = _import_key(verification_key, settings.algorithm)
+        claims = jwt.decode(token, key, algorithms=[settings.algorithm]).claims
+    except JoseError as exc:
+        return VerifyResult.fail(ERROR, f"invalid signature or token format: {exc}")
+    except httpx.HTTPError as exc:
+        return VerifyResult.fail(ERROR, f"could not fetch JWKS: {exc}")
+    except (ValueError, KeyError, TypeError) as exc:
+        return VerifyResult.fail(ERROR, str(exc))
+
+    client_id = str(
+        claims.get("client_id") or claims.get("azp") or claims.get("sub") or "unknown"
+    )
+
+    # 2. Expiry — a real credential, just stale: the agent should re-login.
+    exp = claims.get("exp")
+    if exp is not None and exp < time.time():
+        return VerifyResult.fail(AUTH_REQUIRED, "token expired")
+
+    # 3. Issuer / audience / required scopes — well-signed but not acceptable here → DENIED.
+    if settings.issuer and claims.get("iss") != settings.issuer:
+        return VerifyResult.fail(
+            DENIED, f"issuer mismatch (got {claims.get('iss')!r}, expected {settings.issuer!r})"
+        )
+    if settings.audience and not _audience_ok(settings.audience, claims.get("aud")):
+        return VerifyResult.fail(
+            DENIED, f"audience mismatch (got {claims.get('aud')!r}, expected {settings.audience!r})"
+        )
+
+    scopes, scope_status = _extract_scopes(claims)
+    if scope_status == "invalid_members":
+        # Rejected, matching JWTVerifier. Categorised ERROR (a broken token, not a policy refusal)
+        # and named explicitly, so this is never confused with a legitimate scope shortfall.
+        return VerifyResult.fail(ERROR, "malformed scope claim: non-string member in a list-valued scope")
+    if settings.required_scopes:
+        missing = set(settings.required_scopes) - set(scopes)
+        if missing:
+            # Name the malformed case: otherwise "missing required scopes" reads identically whether
+            # the token carried no scope at all or carried a broken one, and only the second is a
+            # bug to chase at the issuer.
+            detail = " (malformed scope claim)" if scope_status == "malformed_type" else ""
+            return VerifyResult.fail(DENIED, f"missing required scopes: {sorted(missing)}{detail}")
+
+    return VerifyResult.ok(claims=claims, client_id=client_id, scopes=scopes)

kx_auth_core-0.5.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: kx-auth-core
+Version: 0.5.0
+Summary: Lean, fastmcp-free shared core for kx auth: the KX_MCP_AUTH config contract + a joserfc verifier, depended on by both the container (kx-mcp-core) and the client-side kx auth CLI.
+Project-URL: Homepage, https://github.com/KxSystems/kx-mcp-server-container
+Project-URL: Repository, https://github.com/KxSystems/kx-mcp-server-container
+Project-URL: Changelog, https://github.com/KxSystems/kx-mcp-server-container/blob/main/CHANGELOG.md
+License-Expression: Apache-2.0
+Requires-Python: <3.14,>=3.10
+Requires-Dist: cryptography>=50.0.0
+Requires-Dist: httpx<1.0,>=0.28.1
+Requires-Dist: joserfc>=1.1.0
+Requires-Dist: pydantic-settings>=2.14.2
+Description-Content-Type: text/markdown
+
+# kx-auth-core
+
+The lean, deliberately **fastmcp-free** auth core shared by the KX MCP composition container
+(`kx-mcp-core`), the backend bundles, and the client-side `kx auth` CLI (`kx-auth-cli`). It holds
+the auth *mechanisms* so every consumer binds to one implementation:
+
+- **Inbound config + verification** — `AuthSettings` (the `KX_MCP_AUTH*` contract) and a
+  [joserfc](https://jose.authlib.org/) `verify_token` returning a categorised verdict
+  (`ok` / `error` / `auth_required` / `denied`). joserfc is the same JOSE library FastMCP's
+  `JWTVerifier` uses, so server and CLI verification cannot drift.
+- **Outbound identity** — `exchange(config, subject_token)` over the
+  `register_outbound_strategy` registry (`passthrough` / `rfc_8693` / `service_account` / custom),
+  with the `OutboundConfig` / `OutboundCredential` shapes. Pure token→credential; no fastmcp.
+- **Authorization contract** — `AuthzRequest` / `AuthzDecision` (boolean-first, with an
+  `obligations` slot for scope-down), the `AuthzAdapter` protocol, and the
+  `register_authz_adapter` / `decide` registry behind the container's `@authorize` seam.
+- **Identity assertion projection** — `project_principal` / `project_from_claims`, the
+  fastmcp-free (and pykx-free) claims→dict projection the kdb-x identity-assertion path ferries
+  to q.
+
+## Who should depend on it
+
+Backend bundles (for `exchange` and the authz contract) and client-side tooling (the `kx auth`
+CLI). If you are assembling a *server*, depend on `kx-mcp-core` instead — it re-exports these
+seams. Two invariants to respect when contributing: this package never imports `fastmcp` (it ships
+where the agent/client runs), and `verify_token` must stay in agreement with the container's
+`JWTVerifier` (pinned by contract tests in the parent repo).
+
+## Documentation
+
+Full reference in the [`kx-mcp-server-container`](https://github.com/KxSystems/kx-mcp-server-container)
+repository: the [auth guide](https://github.com/KxSystems/kx-mcp-server-container/blob/main/docs/auth.md)
+(inbound modes, outbound strategies, authorization) and the design specs (token-exchange,
+identity-assertion, authorization). All workspace packages version in lockstep from release tags.

kx_auth_core-0.5.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kx_auth_core/__init__.py,sha256=ZyxT0Nkb78wPxVCJx1oI5xUtim4gM3SS9NlqQRTTLfw,1910
+kx_auth_core/assertion.py,sha256=I3mSXtwm5489tacTylEcajeCDBTeGe9HRfldKekniPY,4585
+kx_auth_core/authz.py,sha256=6xaojs7ZA_CMeXK7aifhHEp5SHHucc2HI7ba9ryqe2k,8059
+kx_auth_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kx_auth_core/settings.py,sha256=gXNw5IKGV1s1_fXF6ptD0JqBSMJso3qUOx3Cx-mkKbY,5217
+kx_auth_core/verify.py,sha256=KYbXYACAdV2kMchAmc5wmY7olW0aVXkoFlR8Bd7_YPQ,11379
+kx_auth_core/outbound/__init__.py,sha256=gBrx6wgpYMvPCNPVzC9YSUrVOlnxtLqdgzM1YAFiFtM,833
+kx_auth_core/outbound/claims.py,sha256=770eEFj4RAuV_0ybzRQBLl8GGRowWmnNC4H6qTBDFWg,1059
+kx_auth_core/outbound/config.py,sha256=rbNibjHVOJMaB5jJFGWyh8Z8LiSfHw-lfywzAbajHDI,5456
+kx_auth_core/outbound/strategies.py,sha256=NMUOWDyoNLd84ywvYk4DCxMjjg-oHNx995Fu04TfI3g,8868
+kx_auth_core-0.5.0.dist-info/METADATA,sha256=sUBvo0smaegxKRRo0-mMF4JuGsDngO0Bx-wq1Hy9VDM,2959
+kx_auth_core-0.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+kx_auth_core-0.5.0.dist-info/RECORD,,

kx_auth_core-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any