authweave-otel 7.1.2__tar.gz

authweave_otel-7.1.2/.gitignore

@@ -0,0 +1,36 @@
+# macOS
+.DS_Store
+
+# Python bytecode and native build products
+__pycache__/
+*.py[cod]
+*.so
+
+# Local environments and secrets
+/.venv/
+/.uv-cache/
+.env
+.env.*
+!.env.example
+
+# Packaging output
+/build/
+/dist/
+*.egg-info/
+
+# Test, coverage, and tool caches
+.coverage
+.coverage.*
+/coverage.xml
+/htmlcov/
+/.pytest_cache/
+/.ruff_cache/
+/.cache/
+
+# Generated documentation and code intelligence
+/site/
+/docs/_include/
+/.codegraph/
+
+# Docker reference ephemeral key material
+/docker/reference/http-signatures/_runtime/

authweave_otel-7.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Shepilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

authweave_otel-7.1.2/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: authweave-otel
+Version: 7.1.2
+Summary: OpenTelemetry API-only security observability facade for the AuthWeave stack
+Project-URL: homepage, https://github.com/ZYLVEXT/litestar-auth
+Project-URL: documentation, https://zylvext.github.io/litestar-auth/
+Project-URL: source, https://github.com/ZYLVEXT/litestar-auth
+Project-URL: tracker, https://github.com/ZYLVEXT/litestar-auth/issues
+Author-email: Vladislav Shepilov <shepilov.v@protonmail.com>
+Maintainer-email: Vladislav Shepilov <shepilov.v@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,metrics,observability,opentelemetry,security,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: <3.15.0,>=3.12.0
+Requires-Dist: authweave-core==7.1.2
+Requires-Dist: opentelemetry-api<2.0,>=1.44.0
+Description-Content-Type: text/markdown
+
+# authweave-otel
+
+OpenTelemetry API-only security observability facade for the AuthWeave
+authentication stack.
+
+`authweave-otel` depends only on `opentelemetry-api` and `authweave-core`. It
+never installs an SDK, exporter, sampler, propagator, or `service.name`. Without
+a configured SDK every span and metric is a no-op, so instrumentation is safe and
+free by default.
+
+The application owns the `TracerProvider`/`MeterProvider`, sampling, export, and
+retention. Construct `AuthWeaveTelemetry` with global or explicit providers and
+pass it into your AuthWeave adapter configuration. `LitestarAuth` creates only
+`INTERNAL` child security spans inside the server span produced by normal ASGI
+instrumentation; it never creates a second HTTP span:
+
+```python
+from authweave_otel import AuthWeaveTelemetry
+from litestar_auth import LitestarAuthConfig
+
+telemetry = AuthWeaveTelemetry()
+config = LitestarAuthConfig(
+    # normal required configuration omitted
+    observer=telemetry,
+)
+```
+
+The same observer can be passed to the HTTP-signature/webhook verifier and
+webhook sender constructors. `verify(..., links=(TraceCorrelation(...),))` and
+`send(..., links=...)` attach retry/async causal links without accepting trace
+context as identity. Direct `operation_span()` and metric methods remain
+available for application-owned operations.
+
+## Privacy and abuse resistance
+
+- Attribute keys are allowlisted (`authweave.*` catalog only).
+- Values are truncated to 64 characters and redacted when they match secret
+  canaries (tokens, cookies, PEM headers, payment fragments).
+- Unknown reason codes collapse to `_OTHER` so hostile input cannot grow label
+  cardinality.
+- Baggage extraction/forwarding defaults to off
+  (`DEFAULT_TRACE_CONTEXT_POLICY`); remote parents are never trusted identity.
+- Telemetry never participates in authentication, authorization, replay, or
+  idempotency decisions. Collector/exporter outage must not change auth results.
+- Workload `SecurityEvent` values receive the active `trace_id`/`span_id` for
+  lookup only. The mandatory event callback remains the durable audit channel.
+
+## Catalog and reference stack
+
+Span names, metric names, units, and attribute keys are a versioned catalog. See
+`authweave_otel.catalog`; renames and cardinality growth are breaking changes.
+
+A non-production Collector/Prometheus/Tempo/Grafana stack lives at
+`docker/reference/observability/`. Run `sh docker/reference/observability/verify.sh`
+for the synthetic smoke test and golden Prometheus name checks after the pinned
+OTel→Prometheus translation.

authweave_otel-7.1.2/README.md

@@ -0,0 +1,56 @@
+# authweave-otel
+
+OpenTelemetry API-only security observability facade for the AuthWeave
+authentication stack.
+
+`authweave-otel` depends only on `opentelemetry-api` and `authweave-core`. It
+never installs an SDK, exporter, sampler, propagator, or `service.name`. Without
+a configured SDK every span and metric is a no-op, so instrumentation is safe and
+free by default.
+
+The application owns the `TracerProvider`/`MeterProvider`, sampling, export, and
+retention. Construct `AuthWeaveTelemetry` with global or explicit providers and
+pass it into your AuthWeave adapter configuration. `LitestarAuth` creates only
+`INTERNAL` child security spans inside the server span produced by normal ASGI
+instrumentation; it never creates a second HTTP span:
+
+```python
+from authweave_otel import AuthWeaveTelemetry
+from litestar_auth import LitestarAuthConfig
+
+telemetry = AuthWeaveTelemetry()
+config = LitestarAuthConfig(
+    # normal required configuration omitted
+    observer=telemetry,
+)
+```
+
+The same observer can be passed to the HTTP-signature/webhook verifier and
+webhook sender constructors. `verify(..., links=(TraceCorrelation(...),))` and
+`send(..., links=...)` attach retry/async causal links without accepting trace
+context as identity. Direct `operation_span()` and metric methods remain
+available for application-owned operations.
+
+## Privacy and abuse resistance
+
+- Attribute keys are allowlisted (`authweave.*` catalog only).
+- Values are truncated to 64 characters and redacted when they match secret
+  canaries (tokens, cookies, PEM headers, payment fragments).
+- Unknown reason codes collapse to `_OTHER` so hostile input cannot grow label
+  cardinality.
+- Baggage extraction/forwarding defaults to off
+  (`DEFAULT_TRACE_CONTEXT_POLICY`); remote parents are never trusted identity.
+- Telemetry never participates in authentication, authorization, replay, or
+  idempotency decisions. Collector/exporter outage must not change auth results.
+- Workload `SecurityEvent` values receive the active `trace_id`/`span_id` for
+  lookup only. The mandatory event callback remains the durable audit channel.
+
+## Catalog and reference stack
+
+Span names, metric names, units, and attribute keys are a versioned catalog. See
+`authweave_otel.catalog`; renames and cardinality growth are breaking changes.
+
+A non-production Collector/Prometheus/Tempo/Grafana stack lives at
+`docker/reference/observability/`. Run `sh docker/reference/observability/verify.sh`
+for the synthetic smoke test and golden Prometheus name checks after the pinned
+OTel→Prometheus translation.

authweave_otel-7.1.2/authweave_otel/__init__.py

@@ -0,0 +1,66 @@
+"""OpenTelemetry API-only security observability for the AuthWeave stack."""
+
+from authweave_otel.catalog import (
+    ERROR_OUTCOMES,
+    EXPECTED_OUTCOMES,
+    INSTRUMENTATION_SCOPE,
+    METRIC_CATALOG,
+    OTHER_REASON_CODE,
+    REASON_CODES,
+    SEMANTIC_CONVENTIONS_SCHEMA_URL,
+    AttributeKey,
+    Instrument,
+    MetricSpec,
+    Operation,
+    Outcome,
+    normalize_reason_code,
+    span_name,
+)
+from authweave_otel.privacy import (
+    ALLOWED_ATTRIBUTE_KEYS,
+    DEFAULT_BAGGAGE_KEYS_ALLOWLIST,
+    DEFAULT_TRACE_CONTEXT_POLICY,
+    MAX_ATTRIBUTE_COUNT,
+    MAX_ATTRIBUTE_VALUE_LENGTH,
+    REDACTED_ATTRIBUTE_VALUE,
+    SECRET_CANARY_FRAGMENTS,
+    TraceContextPolicy,
+    contains_secret_canary,
+    sanitize_attributes,
+    truncate_attribute_value,
+)
+from authweave_otel.telemetry import AuthWeaveTelemetry, KeyAgeCallback, OperationScope
+
+__version__ = "7.1.2"
+
+__all__ = (
+    "ALLOWED_ATTRIBUTE_KEYS",
+    "DEFAULT_BAGGAGE_KEYS_ALLOWLIST",
+    "DEFAULT_TRACE_CONTEXT_POLICY",
+    "ERROR_OUTCOMES",
+    "EXPECTED_OUTCOMES",
+    "INSTRUMENTATION_SCOPE",
+    "MAX_ATTRIBUTE_COUNT",
+    "MAX_ATTRIBUTE_VALUE_LENGTH",
+    "METRIC_CATALOG",
+    "OTHER_REASON_CODE",
+    "REASON_CODES",
+    "REDACTED_ATTRIBUTE_VALUE",
+    "SECRET_CANARY_FRAGMENTS",
+    "SEMANTIC_CONVENTIONS_SCHEMA_URL",
+    "AttributeKey",
+    "AuthWeaveTelemetry",
+    "Instrument",
+    "KeyAgeCallback",
+    "MetricSpec",
+    "Operation",
+    "OperationScope",
+    "Outcome",
+    "TraceContextPolicy",
+    "__version__",
+    "contains_secret_canary",
+    "normalize_reason_code",
+    "sanitize_attributes",
+    "span_name",
+    "truncate_attribute_value",
+)

authweave_otel-7.1.2/authweave_otel/catalog.py

@@ -0,0 +1,180 @@
+"""Versioned, immutable telemetry catalog for AuthWeave security instrumentation.
+
+This module is pure data and stdlib only: it never imports ``opentelemetry`` so
+that the span/metric contract can be asserted by golden tests without an SDK.
+Renames, unit changes, or cardinality growth are breaking changes and must be
+caught by :mod:`tests.test_catalog`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from authweave_core import FailureCode, SecurityOperation, SecurityOutcome
+
+#: Instrumentation scope reported for every AuthWeave span and metric.
+INSTRUMENTATION_SCOPE = "authweave"
+
+#: Pinned stable OpenTelemetry Semantic Conventions schema URL. Upgrading this is
+#: a deliberate, reviewed change gated by the golden catalog test.
+SEMANTIC_CONVENTIONS_SCHEMA_URL = "https://opentelemetry.io/schemas/1.30.0"
+
+#: Reason code substituted for any value outside the bounded vocabulary so that a
+#: hostile or unknown reason can never grow metric/label cardinality.
+OTHER_REASON_CODE = "_OTHER"
+
+
+Operation = SecurityOperation
+Outcome = SecurityOutcome
+
+
+#: Outcomes that represent an expected negative decision, never a span ``ERROR``.
+EXPECTED_OUTCOMES = frozenset(
+    {Outcome.NOT_APPLICABLE, Outcome.INVALID, Outcome.REPLAY, Outcome.MISS, Outcome.STALE},
+)
+#: Outcomes that mark a span status ``ERROR`` because verification could not
+#: complete safely or an invariant was violated.
+ERROR_OUTCOMES = frozenset({Outcome.UNAVAILABLE, Outcome.INVARIANT_FAILURE, Outcome.ERROR})
+
+
+class AttributeKey(StrEnum):
+    """Namespaced ``authweave.*`` attribute keys shared by spans and metrics."""
+
+    PROFILE = "authweave.profile"
+    OPERATION = "authweave.operation"
+    OUTCOME = "authweave.outcome"
+    REASON_CODE = "authweave.reason_code"
+    PRINCIPAL_KIND = "authweave.principal_kind"
+    CREDENTIAL_KIND = "authweave.credential_kind"
+
+
+class Instrument(StrEnum):
+    """Supported synchronous instrument kinds in the catalog."""
+
+    COUNTER = "counter"
+    HISTOGRAM = "histogram"
+    OBSERVABLE_GAUGE = "observable_gauge"
+
+
+@dataclass(frozen=True, slots=True)
+class MetricSpec:
+    """One versioned metric definition."""
+
+    name: str
+    instrument: Instrument
+    unit: str
+    description: str
+
+
+#: The frozen metric catalog. Prometheus/OpenMetrics suffixes (``_total`` and
+#: histogram suffixes) are added by the exporter, never encoded here.
+METRIC_CATALOG: tuple[MetricSpec, ...] = (
+    MetricSpec(
+        "authweave.authentication.attempts",
+        Instrument.COUNTER,
+        "{attempt}",
+        "Authentication attempts by profile and outcome.",
+    ),
+    MetricSpec(
+        "authweave.authentication.duration",
+        Instrument.HISTOGRAM,
+        "s",
+        "Coordinator and provider authentication latency.",
+    ),
+    MetricSpec(
+        "authweave.integrity.verifications",
+        Instrument.COUNTER,
+        "{verification}",
+        "DPoP, HTTP signature, and webhook verification outcomes.",
+    ),
+    MetricSpec(
+        "authweave.integrity.duration",
+        Instrument.HISTOGRAM,
+        "s",
+        "Message integrity verification latency.",
+    ),
+    MetricSpec(
+        "authweave.replay.decisions",
+        Instrument.COUNTER,
+        "{decision}",
+        "Replay/nonce store decisions.",
+    ),
+    MetricSpec(
+        "authweave.remote.operation.duration",
+        Instrument.HISTOGRAM,
+        "s",
+        "JWKS, PAR, introspection, and token-exchange latency.",
+    ),
+    MetricSpec(
+        "authweave.remote.operation.attempts",
+        Instrument.COUNTER,
+        "{attempt}",
+        "Remote dependency outcomes without any URL label.",
+    ),
+    MetricSpec(
+        "authweave.cache.requests",
+        Instrument.COUNTER,
+        "{request}",
+        "Cache hit, miss, stale, and error outcomes.",
+    ),
+    MetricSpec(
+        "authweave.key.age",
+        Instrument.OBSERVABLE_GAUGE,
+        "s",
+        "Age of the current trusted key/bundle snapshot.",
+    ),
+    MetricSpec(
+        "authweave.webhook.delivery.attempts",
+        Instrument.COUNTER,
+        "{attempt}",
+        "Webhook delivery outcome and retry class.",
+    ),
+    MetricSpec(
+        "authweave.webhook.delivery.duration",
+        Instrument.HISTOGRAM,
+        "s",
+        "End-to-end webhook sender attempt latency.",
+    ),
+)
+
+#: Protocol-specific reason codes layered on top of the neutral core failure
+#: codes for integrity, nonce, and key-distribution decisions.
+_PROTOCOL_REASON_CODES = frozenset(
+    {
+        "nonce_required",
+        "nonce_stale",
+        "digest_mismatch",
+        "signature_invalid",
+        "key_unknown",
+        "trust_domain_rejected",
+        "store_unavailable",
+        "capacity_exceeded",
+    },
+)
+
+#: Bounded reason-code vocabulary sourced from the neutral core failure codes plus
+#: the protocol-specific codes. Any other value collapses to
+#: :data:`OTHER_REASON_CODE`.
+REASON_CODES: frozenset[str] = frozenset(code.value for code in FailureCode) | _PROTOCOL_REASON_CODES
+
+
+def span_name(operation: Operation) -> str:
+    """Return the fully qualified span name for a logical operation.
+
+    Returns:
+        The ``authweave.<operation>`` span name.
+    """
+    return f"{INSTRUMENTATION_SCOPE}.{operation.value}"
+
+
+def normalize_reason_code(reason_code: str | None) -> str | None:
+    """Collapse any out-of-vocabulary reason code to a safe bounded value.
+
+    Returns:
+        ``None`` when no reason code is supplied, the reason code when it is in
+        the bounded vocabulary, otherwise :data:`OTHER_REASON_CODE`.
+    """
+    if reason_code is None:
+        return None
+    return reason_code if reason_code in REASON_CODES else OTHER_REASON_CODE

authweave_otel-7.1.2/authweave_otel/privacy.py

@@ -0,0 +1,115 @@
+"""Privacy, cardinality, and abuse-resistance policy for AuthWeave telemetry.
+
+These limits apply before attributes leave the process. They do not replace
+application-owned Trace Context boundary policy, SDK Views, or Collector
+attribute filtering — they are the library's last line of defense against
+cardinality growth and secret leakage through labels.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from authweave_otel.catalog import AttributeKey
+
+#: Maximum number of AuthWeave attributes attached to one span or metric point.
+MAX_ATTRIBUTE_COUNT = 8
+
+#: Maximum UTF-8 character length of any AuthWeave attribute value.
+MAX_ATTRIBUTE_VALUE_LENGTH = 64
+
+#: Attribute keys the facade is allowed to emit. Anything else is dropped.
+ALLOWED_ATTRIBUTE_KEYS: frozenset[str] = frozenset(key.value for key in AttributeKey)
+
+#: Baggage key allowlist. Empty by default: baggage is never extracted or
+#: forwarded by AuthWeave instrumentation.
+DEFAULT_BAGGAGE_KEYS_ALLOWLIST: frozenset[str] = frozenset()
+
+#: Substrings that must never appear in emitted attribute values. Used by
+#: secret-canary tests and as documentation of the denial vocabulary.
+SECRET_CANARY_FRAGMENTS: frozenset[str] = frozenset({
+    "Bearer ",
+    "eyJ",  # JWT header prefix
+    "cookie=",
+    "webhook-signature",
+    "dpop ",
+    "-----BEGIN",
+    "password=",
+    "client_secret",
+    "authorization_code",
+    "account_number",
+    "pan=",
+    "cvv=",
+})
+
+
+#: Value substituted when a free-form attribute matches a secret canary.
+REDACTED_ATTRIBUTE_VALUE = "_REDACTED"
+
+
+@dataclass(frozen=True, slots=True)
+class TraceContextPolicy:
+    """Deployer-facing Trace Context and baggage policy defaults.
+
+    AuthWeave never treats a remote parent as trusted identity and never uses
+    baggage for authentication, authorization, replay, or idempotency decisions.
+    Applications enable W3C Trace Context extraction only on explicitly
+    configured boundaries.
+    """
+
+    accept_remote_parent: bool = False
+    extract_baggage: bool = False
+    forward_baggage: bool = False
+    baggage_keys_allowlist: frozenset[str] = DEFAULT_BAGGAGE_KEYS_ALLOWLIST
+
+
+#: Documented library default. Applications may construct a stricter policy;
+#: loosening requires an explicit deployer decision outside this package.
+DEFAULT_TRACE_CONTEXT_POLICY = TraceContextPolicy()
+
+
+def truncate_attribute_value(value: str) -> str:
+    """Bound one attribute value to :data:`MAX_ATTRIBUTE_VALUE_LENGTH`.
+
+    Returns:
+        The original value when it fits, otherwise a truncated prefix.
+    """
+    if len(value) <= MAX_ATTRIBUTE_VALUE_LENGTH:
+        return value
+    return value[:MAX_ATTRIBUTE_VALUE_LENGTH]
+
+
+def sanitize_attributes(attributes: dict[str, str]) -> dict[str, str]:
+    """Drop unknown keys, redact canaries, truncate values, and enforce the budget.
+
+    Unknown keys are discarded. Values matching
+    :data:`SECRET_CANARY_FRAGMENTS` are replaced with
+    :data:`REDACTED_ATTRIBUTE_VALUE`. Remaining values longer than
+    :data:`MAX_ATTRIBUTE_VALUE_LENGTH` are truncated. When more than
+    :data:`MAX_ATTRIBUTE_COUNT` attributes remain after filtering, excess entries
+    are dropped in insertion order so cardinality stays bounded.
+
+    Returns:
+        A new dict safe to attach to a span or metric data point.
+    """
+    sanitized: dict[str, str] = {}
+    for key, value in attributes.items():
+        if key not in ALLOWED_ATTRIBUTE_KEYS:
+            continue
+        if contains_secret_canary(value):
+            sanitized[key] = REDACTED_ATTRIBUTE_VALUE
+        else:
+            sanitized[key] = truncate_attribute_value(value)
+        if len(sanitized) >= MAX_ATTRIBUTE_COUNT:
+            break
+    return sanitized
+
+
+def contains_secret_canary(value: str) -> bool:
+    """Return whether ``value`` matches a documented secret-canary fragment.
+
+    Returns:
+        ``True`` when any fragment in :data:`SECRET_CANARY_FRAGMENTS` appears.
+    """
+    lowered = value.lower()
+    return any(fragment.lower() in lowered for fragment in SECRET_CANARY_FRAGMENTS)

authweave_otel-7.1.2/authweave_otel/telemetry.py

@@ -0,0 +1,448 @@
+"""OpenTelemetry API-only security observability facade.
+
+The facade depends only on ``opentelemetry-api``. Without a configured SDK the
+API returns no-op tracers, meters, and instruments, so instrumentation is safe
+and free. The application owns the ``TracerProvider``/``MeterProvider``, SDK,
+Collector, sampling, export, and retention; this library never installs a global
+SDK, exporter, sampler, or ``service.name``.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from time import perf_counter
+from typing import TYPE_CHECKING
+
+from authweave_core import TraceCorrelation
+from opentelemetry import metrics, trace
+from opentelemetry.trace import Link, SpanContext, SpanKind, TraceFlags
+from opentelemetry.trace.status import Status, StatusCode
+
+from authweave_otel.catalog import (
+    ERROR_OUTCOMES,
+    INSTRUMENTATION_SCOPE,
+    METRIC_CATALOG,
+    SEMANTIC_CONVENTIONS_SCHEMA_URL,
+    AttributeKey,
+    Instrument,
+    Operation,
+    Outcome,
+    normalize_reason_code,
+    span_name,
+)
+from authweave_otel.privacy import sanitize_attributes
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Sequence
+
+    from opentelemetry.metrics import CallbackOptions, Counter, Histogram, Meter, MeterProvider, Observation
+    from opentelemetry.trace import Span, TracerProvider
+
+__version__ = "7.1.2"
+
+type AttributeValue = str
+type Attributes = dict[str, AttributeValue]
+type KeyAgeCallback = Callable[[CallbackOptions], Sequence[Observation]]
+
+
+class OperationScope:
+    """Handle for enriching one in-flight AuthWeave security span."""
+
+    __slots__ = (
+        "_credential_kind",
+        "_operation",
+        "_outcome",
+        "_principal_kind",
+        "_profile",
+        "_reason_code",
+        "_span",
+        "_unexpected",
+    )
+
+    def __init__(
+        self,
+        span: Span,
+        operation: Operation,
+        *,
+        profile: str | None,
+        principal_kind: str | None,
+        credential_kind: str | None,
+    ) -> None:
+        """Bind the scope to its span and low-cardinality context."""
+        self._span = span
+        self._operation = operation
+        self._profile = profile
+        self._principal_kind = principal_kind
+        self._credential_kind = credential_kind
+        self._outcome: Outcome | None = None
+        self._reason_code: str | None = None
+        self._unexpected = False
+
+    def set_outcome(self, outcome: Outcome, *, reason_code: str | None = None) -> None:
+        """Record the terminal outcome and an optional bounded reason code."""
+        self._outcome = outcome
+        self._reason_code = reason_code
+
+    def record_unexpected_exception(self, exc: BaseException) -> None:
+        """Record only the sanitized exception type, never its message or stack."""
+        self._unexpected = True
+        self._span.add_event("exception", {"exception.type": type(exc).__name__})
+
+    def _finalize(self) -> None:
+        attributes: Attributes = {AttributeKey.OPERATION.value: self._operation.value}
+        for key, value in (
+            (AttributeKey.PROFILE, self._profile),
+            (AttributeKey.PRINCIPAL_KIND, self._principal_kind),
+            (AttributeKey.CREDENTIAL_KIND, self._credential_kind),
+        ):
+            if value is not None:
+                attributes[key.value] = value
+        if self._outcome is not None:
+            attributes[AttributeKey.OUTCOME.value] = self._outcome.value
+        normalized = normalize_reason_code(self._reason_code)
+        if normalized is not None:
+            attributes[AttributeKey.REASON_CODE.value] = normalized
+        for key, value in sanitize_attributes(attributes).items():
+            self._span.set_attribute(key, value)
+        if self._unexpected or (self._outcome is not None and self._outcome in ERROR_OUTCOMES):
+            self._span.set_status(Status(StatusCode.ERROR))
+
+
+class AuthWeaveTelemetry:
+    """Typed telemetry facade over the pinned AuthWeave span and metric catalog."""
+
+    __slots__ = ("_counters", "_histograms", "_meter", "_metrics_enabled", "_spans_enabled", "_tracer")
+
+    def __init__(
+        self,
+        *,
+        tracer_provider: TracerProvider | None = None,
+        meter_provider: MeterProvider | None = None,
+        spans_enabled: bool = True,
+        metrics_enabled: bool = True,
+    ) -> None:
+        """Acquire scoped tracer/meter and eagerly build the catalog instruments."""
+        self._spans_enabled = spans_enabled
+        self._metrics_enabled = metrics_enabled
+        self._tracer = trace.get_tracer(
+            INSTRUMENTATION_SCOPE,
+            __version__,
+            tracer_provider,
+            SEMANTIC_CONVENTIONS_SCHEMA_URL,
+        )
+        self._counters: dict[str, Counter] = {}
+        self._histograms: dict[str, Histogram] = {}
+        self._meter: Meter | None = None
+        if metrics_enabled:
+            self._build_instruments(meter_provider)
+
+    def _build_instruments(self, meter_provider: MeterProvider | None) -> None:
+        meter = metrics.get_meter(
+            INSTRUMENTATION_SCOPE,
+            __version__,
+            meter_provider,
+            SEMANTIC_CONVENTIONS_SCHEMA_URL,
+        )
+        self._meter = meter
+        for spec in METRIC_CATALOG:
+            if spec.instrument is Instrument.COUNTER:
+                self._counters[spec.name] = meter.create_counter(spec.name, spec.unit, spec.description)
+            elif spec.instrument is Instrument.HISTOGRAM:
+                self._histograms[spec.name] = meter.create_histogram(spec.name, spec.unit, spec.description)
+            # Observable instruments (key.age) are registered with an application
+            # callback in a dedicated API and are not built eagerly here.
+
+    @contextmanager
+    def operation_span(
+        self,
+        operation: Operation,
+        *,
+        profile: str | None = None,
+        principal_kind: str | None = None,
+        credential_kind: str | None = None,
+        links: Sequence[TraceCorrelation] = (),
+    ) -> Iterator[OperationScope]:
+        """Run one INTERNAL security span, recording only sanitized exceptions.
+
+        Cancellation propagates untouched; only ``Exception`` subclasses are
+        recorded (by sanitized type) before being re-raised.
+
+        Yields:
+            The scope used to set the terminal outcome and reason code.
+        """
+        if not self._spans_enabled:
+            yield OperationScope(
+                trace.INVALID_SPAN,
+                operation,
+                profile=profile,
+                principal_kind=principal_kind,
+                credential_kind=credential_kind,
+            )
+            return
+        with self._tracer.start_as_current_span(
+            span_name(operation),
+            kind=SpanKind.INTERNAL,
+            links=[_otel_link(link) for link in links],
+            record_exception=False,
+            set_status_on_exception=False,
+        ) as span:
+            scope = OperationScope(
+                span,
+                operation,
+                profile=profile,
+                principal_kind=principal_kind,
+                credential_kind=credential_kind,
+            )
+            try:
+                yield scope
+            except Exception as exc:
+                scope.record_unexpected_exception(exc)
+                raise
+            finally:
+                scope._finalize()  # ruff: ignore[private-member-access] - scope is owned by this facade
+
+    @contextmanager
+    def observe(
+        self,
+        operation: Operation,
+        *,
+        profile: str | None = None,
+        principal_kind: str | None = None,
+        credential_kind: str | None = None,
+        links: Sequence[TraceCorrelation] = (),
+    ) -> Iterator[OperationScope]:
+        """Implement the core observer contract and emit matching metrics.
+
+        Yields:
+            The operation scope used by core/provider flow instrumentation.
+        """
+        started = perf_counter()
+        with self.operation_span(
+            operation,
+            profile=profile,
+            principal_kind=principal_kind,
+            credential_kind=credential_kind,
+            links=links,
+        ) as scope:
+            try:
+                yield scope
+            except Exception:
+                scope.set_outcome(Outcome.ERROR)
+                raise
+            finally:
+                if scope._outcome is not None:  # ruff: ignore[private-member-access] - owned observer scope
+                    self._record_observation(scope, perf_counter() - started)
+
+    @staticmethod
+    def current_correlation() -> TraceCorrelation | None:
+        """Return the current valid OpenTelemetry span identifiers."""
+        context = trace.get_current_span().get_span_context()
+        if not context.is_valid:
+            return None
+        return TraceCorrelation(trace_id=f"{context.trace_id:032x}", span_id=f"{context.span_id:016x}")
+
+    def _record_observation(self, scope: OperationScope, duration_seconds: float) -> None:
+        operation = scope._operation  # ruff: ignore[private-member-access] - owned observer scope
+        outcome = scope._outcome  # ruff: ignore[private-member-access] - owned observer scope
+        if outcome is None:
+            return
+        if operation is Operation.AUTHENTICATE:
+            self.record_authentication(
+                profile=scope._profile,  # ruff: ignore[private-member-access] - owned observer scope
+                outcome=outcome,
+                reason_code=scope._reason_code,  # ruff: ignore[private-member-access] - owned observer scope
+                principal_kind=scope._principal_kind,  # ruff: ignore[private-member-access] - owned observer scope
+                credential_kind=scope._credential_kind,  # ruff: ignore[private-member-access] - owned observer scope
+                duration_seconds=duration_seconds,
+            )
+        elif operation in {
+            Operation.VERIFY_DPOP,
+            Operation.VERIFY_HTTP_SIGNATURE,
+            Operation.VERIFY_WEBHOOK,
+            Operation.VALIDATE_SPIFFE_SVID,
+        }:
+            self.record_integrity(
+                operation=operation,
+                profile=scope._profile,  # ruff: ignore[private-member-access] - owned observer scope
+                outcome=outcome,
+                reason_code=scope._reason_code,  # ruff: ignore[private-member-access] - owned observer scope
+                credential_kind=scope._credential_kind,  # ruff: ignore[private-member-access] - owned observer scope
+                duration_seconds=duration_seconds,
+            )
+        elif operation is Operation.REPLAY_CHECK:
+            self.record_replay(profile=scope._profile, outcome=outcome)  # ruff: ignore[private-member-access]
+        elif operation is Operation.WEBHOOK_DELIVER:
+            self.record_webhook_delivery(
+                profile=scope._profile,  # ruff: ignore[private-member-access] - owned observer scope
+                outcome=outcome,
+                duration_seconds=duration_seconds,
+            )
+        else:
+            self.record_remote_operation(
+                operation=operation,
+                outcome=outcome,
+                profile=scope._profile,  # ruff: ignore[private-member-access] - owned observer scope
+                duration_seconds=duration_seconds,
+            )
+
+    def record_authentication(  # ruff: ignore[too-many-arguments] - each parameter is an explicit bounded label
+        self,
+        *,
+        profile: str | None,
+        outcome: Outcome,
+        reason_code: str | None = None,
+        principal_kind: str | None = None,
+        credential_kind: str | None = None,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Record one authentication attempt and optional latency."""
+        attributes = _build_attributes(
+            profile=profile,
+            operation=Operation.AUTHENTICATE,
+            outcome=outcome,
+            reason_code=reason_code,
+            principal_kind=principal_kind,
+            credential_kind=credential_kind,
+        )
+        self._add("authweave.authentication.attempts", attributes)
+        self._record("authweave.authentication.duration", duration_seconds, attributes)
+
+    def record_integrity(  # ruff: ignore[too-many-arguments] - each parameter is an explicit bounded label
+        self,
+        *,
+        operation: Operation,
+        profile: str | None,
+        outcome: Outcome,
+        reason_code: str | None = None,
+        credential_kind: str | None = None,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Record one message-integrity verification and optional latency."""
+        attributes = _build_attributes(
+            profile=profile,
+            operation=operation,
+            outcome=outcome,
+            reason_code=reason_code,
+            principal_kind=None,
+            credential_kind=credential_kind,
+        )
+        self._add("authweave.integrity.verifications", attributes)
+        self._record("authweave.integrity.duration", duration_seconds, attributes)
+
+    def record_replay(self, *, profile: str | None, outcome: Outcome) -> None:
+        """Record one replay/nonce store decision."""
+        attributes = _build_attributes(
+            profile=profile,
+            operation=Operation.REPLAY_CHECK,
+            outcome=outcome,
+            reason_code=None,
+            principal_kind=None,
+            credential_kind=None,
+        )
+        self._add("authweave.replay.decisions", attributes)
+
+    def record_remote_operation(
+        self,
+        *,
+        operation: Operation,
+        outcome: Outcome,
+        profile: str | None = None,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Record one remote dependency attempt and optional latency, never a URL."""
+        attributes = _build_attributes(
+            profile=profile,
+            operation=operation,
+            outcome=outcome,
+            reason_code=None,
+            principal_kind=None,
+            credential_kind=None,
+        )
+        self._add("authweave.remote.operation.attempts", attributes)
+        self._record("authweave.remote.operation.duration", duration_seconds, attributes)
+
+    def record_cache(self, *, operation: Operation, outcome: Outcome) -> None:
+        """Record one cache hit, miss, stale, or error decision."""
+        attributes = _build_attributes(
+            profile=None,
+            operation=operation,
+            outcome=outcome,
+            reason_code=None,
+            principal_kind=None,
+            credential_kind=None,
+        )
+        self._add("authweave.cache.requests", attributes)
+
+    def record_webhook_delivery(
+        self,
+        *,
+        profile: str | None,
+        outcome: Outcome,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Record one webhook delivery attempt and optional end-to-end latency."""
+        attributes = _build_attributes(
+            profile=profile,
+            operation=Operation.WEBHOOK_DELIVER,
+            outcome=outcome,
+            reason_code=None,
+            principal_kind=None,
+            credential_kind=None,
+        )
+        self._add("authweave.webhook.delivery.attempts", attributes)
+        self._record("authweave.webhook.delivery.duration", duration_seconds, attributes)
+
+    def register_key_age(self, callback: KeyAgeCallback) -> None:
+        """Register the application callback backing the ``authweave.key.age`` gauge.
+
+        The callback must return bounded, low-cardinality observations and never a
+        key identifier or URL. It is a no-op when metrics are disabled.
+        """
+        if not self._metrics_enabled or self._meter is None:
+            return
+        spec = next(spec for spec in METRIC_CATALOG if spec.name == "authweave.key.age")
+        self._meter.create_observable_gauge(spec.name, [callback], spec.unit, spec.description)
+
+    def _add(self, name: str, attributes: Attributes) -> None:
+        if self._metrics_enabled:
+            self._counters[name].add(1, attributes)
+
+    def _record(self, name: str, value: float | None, attributes: Attributes) -> None:
+        if self._metrics_enabled and value is not None:
+            self._histograms[name].record(value, attributes)
+
+
+def _build_attributes(  # ruff: ignore[too-many-arguments] - each label is an explicit bounded dimension
+    *,
+    profile: str | None,
+    operation: Operation,
+    outcome: Outcome,
+    reason_code: str | None,
+    principal_kind: str | None,
+    credential_kind: str | None,
+) -> Attributes:
+    attributes: Attributes = {
+        AttributeKey.OPERATION.value: operation.value,
+        AttributeKey.OUTCOME.value: outcome.value,
+    }
+    normalized = normalize_reason_code(reason_code)
+    for key, value in (
+        (AttributeKey.PROFILE, profile),
+        (AttributeKey.REASON_CODE, normalized),
+        (AttributeKey.PRINCIPAL_KIND, principal_kind),
+        (AttributeKey.CREDENTIAL_KIND, credential_kind),
+    ):
+        if value is not None:
+            attributes[key.value] = value
+    return sanitize_attributes(attributes)
+
+
+def _otel_link(correlation: TraceCorrelation) -> Link:
+    return Link(
+        SpanContext(
+            trace_id=int(correlation.trace_id, 16),
+            span_id=int(correlation.span_id, 16),
+            is_remote=True,
+            trace_flags=TraceFlags(TraceFlags.DEFAULT),
+        ),
+    )

authweave_otel-7.1.2/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "authweave-otel"
+version = "7.1.2"
+description = "OpenTelemetry API-only security observability facade for the AuthWeave stack"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Vladislav Shepilov", email = "shepilov.v@protonmail.com"},
+]
+maintainers = [
+    {name = "Vladislav Shepilov", email = "shepilov.v@protonmail.com"},
+]
+keywords = ["opentelemetry", "observability", "authentication", "security", "metrics", "tracing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: System :: Monitoring",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = "<3.15.0,>=3.12.0"
+dependencies = [
+    "authweave-core==7.1.2",
+    "opentelemetry-api>=1.44.0,<2.0",
+]
+
+[project.urls]
+homepage = "https://github.com/ZYLVEXT/litestar-auth"
+documentation = "https://zylvext.github.io/litestar-auth/"
+source = "https://github.com/ZYLVEXT/litestar-auth"
+tracker = "https://github.com/ZYLVEXT/litestar-auth/issues"
+
+[build-system]
+requires = ["hatchling==1.31.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["authweave_otel"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["authweave_otel"]
+
+[dependency-groups]
+dev = [
+    "opentelemetry-sdk>=1.44.0,<2.0",
+]
+
+[tool.coverage.run]
+source = ["authweave_otel"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.src]
+include = ["authweave_otel", "tests"]