idside 0.1.0.dev0__py3-none-any.whl

idside/_jcs.py

@@ -0,0 +1,130 @@
+# Patents: https://sdk.idside.eu/patents
+# This software may be covered by the patents and applications listed there.
+
+"""Minimal RFC 8785 (JCS) canonicalization — internal module.
+
+The ``request_hash`` bound into ACT tokens is computed over the JCS canonical
+form of the AI call payload, so every ID Side SDK (Python today, Node later)
+produces bit-identical hashes for the same payload and any auditor can
+recompute them. Implemented locally: the JSON subset the SDK needs is small
+enough to keep in-tree, fully tested, and free of runtime dependencies.
+
+Scope: JSON-compatible values only (``dict``/``list``/``str``/``int``/
+``float``/``bool``/``None``). Anything else must be normalized *before*
+calling :func:`canonicalize` (see ``ProviderAdapter.extract_request_metadata``).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+__all__ = ["canonicalize"]
+
+#: Largest integer magnitude exactly representable as an IEEE-754 double (2^53).
+#: Beyond it, JavaScript SDKs would parse a different value and hashes diverge.
+_MAX_SAFE_INT = 2**53
+
+
+def canonicalize(value: Any) -> bytes:
+    """Serialize ``value`` per RFC 8785 and return the canonical UTF-8 bytes.
+
+    Raises ``ValueError`` for anything outside the JCS-serializable domain:
+    non-JSON types, non-string dict keys, NaN/Infinity, integers beyond
+    IEEE-754 safe range, or strings containing lone surrogates.
+    """
+    out: list[str] = []
+    _write(value, out)
+    # UnicodeEncodeError (a ValueError subclass) surfaces lone surrogates here.
+    return "".join(out).encode("utf-8")
+
+
+def _write(value: Any, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif isinstance(value, bool):
+        out.append("true" if value else "false")
+    elif isinstance(value, str):
+        out.append(json.dumps(value, ensure_ascii=False))
+    elif isinstance(value, int):
+        out.append(_format_int(value))
+    elif isinstance(value, float):
+        out.append(_format_float(value))
+    elif isinstance(value, list):
+        out.append("[")
+        for i, item in enumerate(value):
+            if i:
+                out.append(",")
+            _write(item, out)
+        out.append("]")
+    elif isinstance(value, dict):
+        out.append("{")
+        for i, (key, item) in enumerate(_sorted_items(value)):
+            if i:
+                out.append(",")
+            out.append(json.dumps(key, ensure_ascii=False))
+            out.append(":")
+            _write(item, out)
+        out.append("}")
+    else:
+        raise ValueError(f"type '{type(value).__name__}' is not JSON-serializable")
+
+
+def _sorted_items(value: dict[Any, Any]) -> list[tuple[str, Any]]:
+    for key in value:
+        if not isinstance(key, str):
+            raise ValueError(
+                f"object key {key!r} is not a string (JSON object keys must be)"
+            )
+    # RFC 8785 §3.2.3: keys sort by UTF-16 code units, not Unicode code points
+    # (an emoji, encoded as a surrogate pair, sorts before U+E000..U+FFFF).
+    return sorted(value.items(), key=lambda kv: kv[0].encode("utf-16-be"))
+
+
+def _format_int(value: int) -> str:
+    if abs(value) > _MAX_SAFE_INT:
+        raise ValueError(
+            f"integer {value} exceeds the IEEE-754 safe range (±2^53); "
+            "it would not hash identically across SDK languages"
+        )
+    return str(value)
+
+
+def _format_float(value: float) -> str:
+    """Format per ECMAScript ``Number::toString`` (RFC 8785 §3.2.2.3)."""
+    if math.isnan(value) or math.isinf(value):
+        raise ValueError("NaN and Infinity are not valid JSON numbers")
+    if value == 0.0:
+        return "0"  # ECMAScript serializes both +0 and -0 as "0"
+    sign = ""
+    if value < 0:
+        sign = "-"
+        value = -value
+    # repr() yields the shortest digits that round-trip, same digits as ES6.
+    text = repr(value)
+    if "e" in text:
+        mantissa, _, exp_text = text.partition("e")
+        exp10 = int(exp_text)
+    else:
+        mantissa, exp10 = text, 0
+    int_part, _, frac_part = mantissa.partition(".")
+    digits_value = int(int_part + frac_part)
+    exponent = exp10 - len(frac_part)
+    while digits_value % 10 == 0:
+        digits_value //= 10
+        exponent += 1
+    digits = str(digits_value)
+    k = len(digits)
+    n = k + exponent  # value == 0.<digits> * 10^n
+    if k <= n <= 21:
+        body = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + digits
+    else:
+        head = digits[0] + ("." + digits[1:] if k > 1 else "")
+        exp_out = n - 1
+        body = f"{head}e{'+' if exp_out >= 0 else '-'}{abs(exp_out)}"
+    return sign + body

idside/_log.py

@@ -0,0 +1,163 @@
+# Patents: https://sdk.idside.eu/patents
+# This software may be covered by the patents and applications listed there.
+
+"""The journal: enough to debug a call that did not go out, and nothing more.
+
+A fail-closed SDK with no journal is undebuggable at a customer site. When a
+call does not leave the process, the developer needs to learn which call site
+was recognised, which parameters a user's answer forced, how long the cloud
+took, and whether it was reached at all. Every one of those is a fact about
+*their own* request.
+
+Three rules shape everything here, and the first two are refusals.
+
+**Nothing secret is ever emitted.** Not the ID Side key, not the provider key,
+not the end user's identifier in the clear, not a UBT, not a prompt, not an ACT
+token, not a credential. Invariant #7 says a credential is a secret — never
+logged, never in an error message — and the person on the other end deserves the
+same treatment. What is emitted is either a fact about the developer's own
+configuration (the provider, the call site, the model, the posture *label*) or a
+value that is already a digest.
+
+**Silent by default.** This module attaches a ``NullHandler`` and nothing else.
+It never calls ``basicConfig``, never touches the root logger, never writes to a
+stream. Without that handler, Python's ``lastResort`` prints WARNING and above
+to stderr, so "we only log at DEBUG" would not have been an answer on its own: a
+library that prints uninvited is a library that gets removed.
+
+**Observation is not influence** (invariant #8). A logging handler is arbitrary
+application code running in the middle of the enforcement path, and formatters
+routinely walk and normalise what they are handed. So a record is built from
+scalars and fresh copies, never from the live objects the SDK is about to act
+on — no ``ConsentDecision``, no kwargs dict, no route. A handler that mutates
+everything it is shown changes nothing about the call that follows, and a test
+pins exactly that. There is no hook, no callback and no ``on_event=`` here
+either: a point where an application could watch *and* answer would be the
+opaque tunnel through the back door.
+
+The net (``_guard.py``) uses none of this. It stays blind by design, and
+observability is not a reason to give it a first thing to record.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import time
+from typing import Any
+
+__all__ = ["event", "logger", "pseudonym", "timer"]
+
+_LOGGER_NAME = "idside"
+
+#: Per-process salt for the subject pseudonym. Random, never persisted, never
+#: emitted. A ``user_id`` is low-entropy on purpose — ``usr_marie_456`` is a
+#: dictionary away — so an unsalted digest of one is not a pseudonym but an
+#: encoding: anyone holding the log hashes their guesses and reads the names
+#: back. Salting per process keeps the only property debugging actually needs,
+#: correlating one user's calls *within one log*, and drops the one nobody
+#: asked for, recognising that user across logs, machines or restarts.
+_SALT = os.urandom(32)
+
+#: Enough digest to tell users apart in a log, far too little to attack.
+_PSEUDONYM_CHARS = 12
+
+#: The request hash is already a digest and is what the ledger indexes, so it is
+#: the honest answer to "which proof was minted for this call?" — the ACT token
+#: itself is bearer material and is never emitted. Truncated anyway: a full hash
+#: of a short prompt is a dictionary attack away from the prompt.
+_HASH_CHARS = 12
+
+
+def logger() -> logging.Logger:
+    """The package logger. The application owns its handlers, level and format."""
+    return logging.getLogger(_LOGGER_NAME)
+
+
+def pseudonym(value: object) -> str:
+    """A stable, unforgeable stand-in for one end user, for this process only.
+
+    Accepts a ``user_id`` or a UBT and treats both the same way: what comes back
+    names nobody, and the value that went in cannot be recovered from it or
+    guessed into it.
+    """
+    digest = hashlib.sha256(_SALT + str(value).encode("utf-8")).hexdigest()
+    return digest[:_PSEUDONYM_CHARS]
+
+
+def short_hash(request_hash: object) -> str:
+    """The correlating half of a ``sha256:<hex>`` request hash."""
+    text = str(request_hash)
+    _, _, hexpart = text.rpartition(":")
+    return hexpart[:_HASH_CHARS]
+
+
+class timer:
+    """Milliseconds spent inside the block, for the one hop worth measuring.
+
+    Monotonic: a journal that reports a negative authorize because NTP stepped
+    the clock is a journal that gets distrusted for the one number it exists to
+    report.
+    """
+
+    __slots__ = ("_started", "ms")
+
+    def __init__(self) -> None:
+        self.ms = 0
+
+    def __enter__(self) -> timer:
+        self._started = time.monotonic_ns()
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.ms = (time.monotonic_ns() - self._started) // 1_000_000
+
+
+def event(name: str, **fields: Any) -> None:
+    """Emit one event at DEBUG, as a stable text line and a structured payload.
+
+    Both, because applications read logs both ways: a terminal reads the
+    message, an aggregator reads ``record.idside``. A field present in one and
+    absent from the other would be a field somebody debugs without.
+
+    Field order is the caller's, and stable, so two runs of the same path
+    produce comparable lines — which is what lets the cross-SDK parity script
+    diff Python's journal against Node's. ``None`` values are dropped rather
+    than rendered: "the cloud named no posture" is said by the absence of
+    ``posture=``, not by ``posture=None``.
+
+    Callers pass scalars and copies. Nothing here reaches into a live object,
+    and nothing a handler does to what it receives can travel back.
+    """
+    log = logger()
+    if not log.isEnabledFor(logging.DEBUG):
+        return  # do not pay for formatting nobody will read
+    payload = {key: value for key, value in fields.items() if value is not None}
+    rendered = " ".join(f"{key}={_render(value)}" for key, value in payload.items())
+    log.debug(
+        f"{name} {rendered}" if rendered else name,
+        extra={"idside": {"event": name, **payload}},
+    )
+
+
+def _render(value: Any) -> str:
+    """One value, in a form that survives a grep and never spans a line.
+
+    A list becomes ``a+b`` rather than ``['a', 'b']``: the parameters a consent
+    state forced are read far more often than they are parsed, and the sorted
+    join is identical in both SDKs, which is what the parity script compares.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple)):
+        return (
+            "+".join(str(item) for item in sorted(str(item) for item in value)) or "-"
+        )
+    return str(value).replace(" ", "_")
+
+
+# Silent by default, and this line is what makes it true: with no handler at
+# all, Python's `lastResort` prints WARNING and above straight to stderr. The
+# application adds its own handler if it wants to read any of this.
+logging.getLogger(_LOGGER_NAME).addHandler(logging.NullHandler())

idside/_routing.py

@@ -0,0 +1,280 @@
+# Patents: https://sdk.idside.eu/patents
+# This software may be covered by the patents and applications listed there.
+
+"""Credential routing: which of the developer's credentials carries this call.
+
+No provider lets a developer switch training off per request. The setting lives
+on the credential — per project at OpenAI and Gemini, per workspace at
+Anthropic, per organisation at Mistral — so one key means one posture for every
+user of the app at once. A developer who provisions one credential per posture
+lets the SDK send each call on the one matching that user's answer, and the
+account control becomes a personal one. It is the only route by which a
+training opt-out can be honoured per user today.
+
+What this module does and does not decide:
+
+- it does **not** decide which posture a consent state calls for. That is
+  policy, it lives in the cloud, and the SDK is told the answer
+  (``credential_posture`` on the authorize response). There is no
+  consent→credential table here, exactly as there is no consent→params one;
+- it does **not** let the developer choose either. They label what they hold;
+  the label is matched against the cloud's answer. A callback would hand them
+  the user's preferences, which is invariant #1;
+- it fails closed. A posture nobody provisioned stops the call, because the
+  alternative is sending it on a credential the user's answer excludes, with
+  nothing anywhere to say so.
+
+This module is internal (``_routing``). The public surface is the
+``credentials=`` argument of :func:`idside.consent.wrap`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from idside.exceptions import CredentialRoutingError, MissingCredentialError
+from idside.providers import CredentialRouting, ProviderDescriptor
+
+#: Fallback shape for a routed header value when the descriptor pins no pattern:
+#: printable ASCII, no space, no control character. Its job is narrow but not
+#: optional — the value is written into an outgoing HTTP header, and a CR or LF
+#: in it is header injection on the developer's own provider request.
+_SAFE_HEADER_VALUE = re.compile(r"[!-~]{1,200}")
+
+
+@dataclass(frozen=True)
+class Route:
+    """Where one call must go once the cloud has named a posture.
+
+    Exactly one of the two mechanisms applies, and which one is a property of
+    the provider, not of the call: ``headers`` for a provider that validates a
+    per-request credential header (OpenAI's ``OpenAI-Project``), ``call`` for
+    everyone else, where the key is fixed at client construction and switching
+    posture means switching client. A route with neither is the ordinary case:
+    the cloud named no posture, and nothing about the call changes.
+    """
+
+    headers: dict[str, str] = field(default_factory=dict)
+    call: Callable[..., Any] | None = None
+
+
+#: The unrouted call: no header to add, and the client the developer wrapped.
+NO_ROUTE = Route()
+
+
+def _resolve(client: Any, path: Sequence[str]) -> Any:
+    """Walk an attribute path on a client, or return None if it does not exist."""
+    current = client
+    for attr in path:
+        if not hasattr(current, attr):
+            return None
+        current = getattr(current, attr)
+    return current
+
+
+class CredentialRouter:
+    """The developer's labelled credentials, resolved once at ``wrap()`` time.
+
+    Everything that can be checked early is checked here rather than on the AI
+    request path: an unroutable provider, a bare identifier where only a client
+    will do, an identifier of the wrong shape, an alternative client missing the
+    endpoint being wrapped. A developer meets those at startup, not in
+    production, and never as a call that quietly went out on the wrong account.
+    """
+
+    def __init__(
+        self,
+        descriptor: ProviderDescriptor,
+        credentials: Mapping[str, Any],
+        call_sites: Sequence[tuple[str, Sequence[str]]],
+        *,
+        is_enforced: Callable[[Any], bool] = lambda method: False,
+    ) -> None:
+        """Validate and resolve ``credentials`` against a provider and a client.
+
+        ``call_sites`` are the endpoints ``wrap()`` is about to patch, as
+        ``(id, path)`` pairs — one per *method*, so an aliased endpoint appears
+        once per alias with its own path. An alternative client must expose
+        every one of them, or a call routed to it would find nothing to call,
+        or worse, the wrong thing: two methods may share a wire id and still
+        behave differently (``messages.parse`` is not ``messages.create``).
+
+        ``is_enforced`` recognises a method this SDK has already patched. It is
+        injected so the enforcement marker stays private to
+        :mod:`idside.consent`; routing to an already-wrapped client would
+        authorize twice and stack two ACT tokens onto one request.
+        """
+        if not isinstance(credentials, Mapping):
+            raise CredentialRoutingError(
+                "consent.wrap(credentials=…) takes a mapping of posture label → "
+                f"credential, not {type(credentials).__name__}. The label is what "
+                "the ID Side cloud names when it routes a call; a bare sequence "
+                "of credentials would carry no posture at all."
+            )
+        routing = descriptor.credential_routing
+        if routing is None:
+            raise CredentialRoutingError(
+                f"consent.wrap() was given credentials for '{descriptor.name}', "
+                "which declares no credential routing: it exposes no account-level "
+                "privacy posture a second credential could carry, so routing "
+                "between two of them would change nothing for the user. Remove the "
+                "credentials argument."
+            )
+
+        self._descriptor = descriptor
+        self._routing = routing
+        self._headers: dict[str, dict[str, str]] = {}
+        self._calls: dict[tuple[str, tuple[str, ...]], Callable[..., Any]] = {}
+
+        for posture, credential in credentials.items():
+            if not isinstance(posture, str) or not posture.strip():
+                raise CredentialRoutingError(
+                    f"Every credential passed to consent.wrap() must be labelled "
+                    f"with the posture it carries, and {posture!r} is not a usable "
+                    "label. The label is what the ID Side cloud names when it "
+                    "routes a call, so it must match the one configured for this "
+                    "app in the dashboard."
+                )
+            if isinstance(credential, str):
+                self._headers[posture] = {
+                    self._header_name(posture): self._checked_value(credential, posture)
+                }
+            else:
+                self._add_client(posture, credential, call_sites, is_enforced)
+
+        #: Sorted so two processes holding the same configuration send the cloud
+        #: the same payload.
+        self.postures: tuple[str, ...] = tuple(sorted(credentials))
+
+    # ── configuration ──────────────────────────────────────────────────────
+
+    def _header_name(self, posture: str) -> str:
+        """The routing header, or explain why a string cannot work here."""
+        if self._routing.header:
+            return self._routing.header
+        raise CredentialRoutingError(
+            f"The credential labelled '{posture}' is a bare identifier, but "
+            f"'{self._descriptor.name}' reads no per-request header naming a "
+            f"{self._routing.unit}: its key is chosen when the client is built. "
+            f"Pass a second client constructed with that {self._routing.unit}'s "
+            "key instead — a string here would be accepted and never sent, which "
+            "is the one outcome routing exists to prevent."
+        )
+
+    def _checked_value(self, value: str, posture: str) -> str:
+        """Validate a routed header value; never echo it back on failure."""
+        pattern = self._routing.header_value_pattern
+        ok = (
+            re.fullmatch(pattern, value)
+            if pattern
+            else _SAFE_HEADER_VALUE.fullmatch(value)
+        )
+        if ok:
+            return value
+        expected = f" (expected {pattern})" if pattern else ""
+        raise CredentialRoutingError(
+            f"The credential labelled '{posture}' is not a "
+            f"{self._descriptor.name} {self._routing.unit} identifier{expected}. "
+            "The value is not repeated here on purpose: if what you pasted is an "
+            "API key, it is a secret, and it was about to travel in a header that "
+            "is not the one that carries it."
+        )
+
+    def _add_client(
+        self,
+        posture: str,
+        credential: Any,
+        call_sites: Sequence[tuple[str, Sequence[str]]],
+        is_enforced: Callable[[Any], bool],
+    ) -> None:
+        """Resolve every wrapped endpoint on an alternative provider client."""
+        self._check_same_provider(posture, credential)
+        for _site_id, path in call_sites:
+            method = _resolve(credential, path)
+            if not callable(method):
+                raise CredentialRoutingError(
+                    f"The client passed as credential '{posture}' does not expose "
+                    f"'{'.'.join(path)}', which consent.wrap() is enforcing on the "
+                    "client you wrapped. A call routed to it would have nothing to "
+                    "call. Pass a client of the same kind, built with that "
+                    f"{self._routing.unit}'s key."
+                )
+            if is_enforced(method):
+                raise CredentialRoutingError(
+                    f"The client passed as credential '{posture}' is already "
+                    "wrapped by consent.wrap(). Routing a call to it would "
+                    "authorize the same request twice and stack two ACT tokens on "
+                    "it. Pass the unwrapped client."
+                )
+            self._calls[(posture, tuple(path))] = method
+
+    def _check_same_provider(self, posture: str, credential: Any) -> None:
+        """Refuse a routed client that belongs to a different provider.
+
+        Best effort, and it only ever refuses on a positive identification. It
+        matters because the shapes coincide: an ``OpenAI`` client pointed at
+        another vendor's base URL is still an ``OpenAI`` client, so every call
+        site resolves and the only thing that differs is which company receives
+        the prompt.
+        """
+        from idside.adapters import get_adapter_for
+        from idside.exceptions import UnsupportedProviderError
+
+        try:
+            detected = get_adapter_for(credential).name
+        except UnsupportedProviderError:
+            return  # unidentifiable is not evidence of anything
+        if detected != self._descriptor.name:
+            raise CredentialRoutingError(
+                f"The client passed as credential '{posture}' is a "
+                f"'{detected}' client, but consent.wrap() is enforcing "
+                f"'{self._descriptor.name}'. Routing between two providers would "
+                "send the request to a company the user's answer never mentioned."
+            )
+
+    # ── the request path ───────────────────────────────────────────────────
+
+    def route(self, posture: str, call_path: Sequence[str]) -> Route:
+        """The route for ``posture``, or refuse the call.
+
+        Called once per AI request, after the cloud has named the posture this
+        user's answer requires. ``call_path`` is the attribute path of the method
+        being called, not the endpoint's wire id: an aliased method must land on
+        the same method of the alternative client.
+        """
+        headers = self._headers.get(posture)
+        if headers is not None:
+            return Route(headers=headers)
+        call = self._calls.get((posture, tuple(call_path)))
+        if call is not None:
+            return Route(call=call)
+        raise MissingCredentialError(
+            missing_message(self._descriptor, posture, self.postures),
+            posture=posture,
+            provider=self._descriptor.name,
+            provisioned=self.postures,
+        )
+
+
+def missing_message(
+    descriptor: ProviderDescriptor, posture: str, provisioned: tuple[str, ...]
+) -> str:
+    """Say what is missing, in the provider's own vocabulary.
+
+    Names the labels that do exist and never a credential: the labels are the
+    developer's own words for their configuration, the credentials are secrets.
+    """
+    routing: CredentialRouting | None = descriptor.credential_routing
+    unit = routing.unit if routing else "credential"
+    have = ", ".join(f"'{name}'" for name in provisioned) if provisioned else "none"
+    return (
+        f"This user's consent requires the '{posture}' credential for "
+        f"'{descriptor.name}', and consent.wrap() was given none carrying it "
+        f"(provisioned: {have}). The AI call was not made: sending it on another "
+        f"{unit} would place this user under a privacy regime they declined, and "
+        f"nothing would record that it happened. Provision a {unit} with that "
+        f"posture and pass it to consent.wrap() as credentials={{'{posture}': …}}."
+    )