libb-util 0.0.44__tar.gz → 0.0.45__tar.gz

{libb_util-0.0.44 → libb_util-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libb-util
-Version: 0.0.44
+Version: 0.0.45
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11

{libb_util-0.0.44 → libb_util-0.0.45}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "libb-util"
-version = "0.0.44"
+version = "0.0.45"
 readme = "README.md"
 description = "libb utility modules for python"
 authors = [{name = "bissli", email = "bissli@xyz.org"}]
@@ -45,7 +45,7 @@ libb-tokenauth = "libb.tokenauth:run_cli"
 
 [tool.poetry]
 name = "libb-util"
-version = "0.0.44"
+version = "0.0.45"
 readme = "README.md"
 description = "libb utility modules for python"
 authors = ["bissli"]

{libb_util-0.0.44 → libb_util-0.0.45}/rust/Cargo.lock

@@ -19,9 +19,9 @@ checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
 [[package]]
 name = "cc"
-version = "1.2.64"
+version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f"
+checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -65,15 +65,15 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.186"
+version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
 [[package]]
 name = "memchr"
-version = "2.8.2"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "memoffset"
@@ -92,15 +92,15 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "portable-atomic"
-version = "1.13.1"
+version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.106"
+version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
  "unicode-ident",
 ]
@@ -180,18 +180,18 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.45"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
  "proc-macro2",
 ]
 
 [[package]]
 name = "regex"
-version = "1.12.4"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -201,9 +201,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.14"
+version = "0.4.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -218,9 +218,9 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rustversion"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
 name = "shlex"
@@ -230,9 +230,9 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "syn"
-version = "2.0.117"
+version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
  "proc-macro2",
  "quote",

{libb_util-0.0.44 → libb_util-0.0.45}/src/libb/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.0.44'
+__version__ = '0.0.45'
 
 # public
 version = __version__

{libb_util-0.0.44 → libb_util-0.0.45}/src/libb/tokenauth.py

@@ -15,7 +15,7 @@ Layers, low to high:
 - :func:`verify_token` -- authorize a presented key: static break-glass
   token (constant time) then the registry, failing closed.
 - :class:`ApiTokenMiddleware` -- a raw-ASGI gate that runs a
-  ``(presented) -> bool`` verifier (typically
+  ``(presented) -> str | None`` verifier (typically
   ``functools.partial(verify_token, ...)``) for chosen path prefixes.
 - :func:`mint_key` / :func:`revoke_key` / :func:`list_clients` and the
   ``libb-tokenauth`` CLI (:func:`run_cli`) -- provisioning.
@@ -23,6 +23,18 @@ Layers, low to high:
 Both :func:`verify_token` and :class:`ApiTokenMiddleware` independently
 fail closed; used together that is deliberate defense-in-depth.
 
+The authorization layers return the *identity* they authorized -- a
+client_id string, or None when denied -- rather than a bare bool, and
+:class:`ApiTokenMiddleware` publishes it at ``scope['state']['client_id']``
+so a downstream handler can log which human made the call. Returning an
+identity keeps the truthiness contract of the old bool, so ``if
+verify_token(...)`` still reads correctly.
+
+A credential is read from the ``X-API-Key`` or ``Authorization: Bearer``
+header only. A ``?key=`` query parameter is deliberately not accepted:
+query strings are recorded verbatim by proxy and web-server access logs,
+so that form turns every request into a credential disclosure.
+
 Expected table shape::
 
     client_id   (S)  -- partition key
@@ -39,12 +51,13 @@ import logging
 import secrets
 from collections.abc import Callable, Iterable
 from typing import Any, Literal, NamedTuple
-from urllib.parse import parse_qs
 
 logger = logging.getLogger(__name__)
 
 __all__ = [
     'KEY_SHA256_INDEX',
+    'STATIC_TOKEN_CLIENT_ID',
+    'UNKNOWN_CLIENT_ID',
     'ClientExistsError',
     'ClientNotFoundError',
     'ClientRecord',
@@ -59,6 +72,28 @@ __all__ = [
 
 KEY_SHA256_INDEX = 'key_sha256-index'
 
+STATIC_TOKEN_CLIENT_ID = 'static-token'
+
+UNKNOWN_CLIENT_ID = 'unknown'
+
+
+def _as_client_id(result: Any) -> str | None:
+    """Normalize an authorizer result to a client_id or None.
+
+    Keeps the identity published downstream typed as ``str | None`` even
+    when a caller supplies a pre-existing ``-> bool`` callable, so a raw
+    ``True`` can never reach a log line posing as a client_id.
+
+    :param result: Whatever an injected ``registry_check`` or ``verify``
+        returned.
+    :returns: The string unchanged when non-empty; ``UNKNOWN_CLIENT_ID``
+        for a truthy non-string (a legacy bool-returning callable); None
+        for anything falsy.
+    """
+    if isinstance(result, str):
+        return result or None
+    return UNKNOWN_CLIENT_ID if result else None
+
 
 class ClientRecord(NamedTuple):
     """A registry client row: id, status, and creation time."""
@@ -109,18 +144,23 @@ def key_active_in_registry(
     table: str,
     region: str | None = None,
     dynamodb_client: Any = None,
-) -> bool:
-    """Return True iff a hashed key maps to an active client.
+) -> str | None:
+    """Return the client_id a hashed key maps to, if that client is active.
 
-    Queries the ``key_sha256-index`` GSI for a single match and reports
-    its ``active`` flag. Does not catch errors and does not cache --
-    callers decide both.
+    Queries the ``key_sha256-index`` GSI for a single match and reports the
+    matched client's identity. Does not catch errors and does not cache --
+    callers decide both. The GSI query already returns the whole row, so
+    surfacing the identity costs nothing over the previous boolean and is
+    what lets a caller attribute a request to a named client. An active row
+    whose ``client_id`` is missing or empty denies, rather than authorizing
+    an unattributable caller.
 
     :param key_sha256: SHA-256 hex digest of the presented key.
     :param table: DynamoDB registry table name.
     :param region: AWS region for a default boto3 client (optional).
     :param dynamodb_client: Injected boto3 DynamoDB client (optional).
-    :returns: True if a matching client item is active.
+    :returns: The matched ``client_id`` when the item exists and is
+        active, else None.
     """
     client = _dynamodb_client(dynamodb_client, region)
     response = client.query(
@@ -132,8 +172,10 @@ def key_active_in_registry(
         )
     items = response.get('Items', [])
     if not items:
-        return False
-    return items[0].get('active', {}).get('BOOL', False)
+        return None
+    if not items[0].get('active', {}).get('BOOL', False):
+        return None
+    return items[0].get('client_id', {}).get('S', '') or None
 
 
 def verify_token(
@@ -143,9 +185,9 @@ def verify_token(
     static_token: str | None = None,
     region: str | None = None,
     dynamodb_client: Any = None,
-    registry_check: Callable[[str], bool] | None = None,
-) -> bool:
-    """Authorize a presented key, failing closed.
+    registry_check: Callable[[str], str | None] | None = None,
+) -> str | None:
+    """Authorize a presented key and return the identity, failing closed.
 
     The static break-glass token is checked first (constant time). The
     registry is then consulted via ``registry_check`` if given, else via a
@@ -158,6 +200,9 @@ def verify_token(
     To bind this to :class:`ApiTokenMiddleware`, wrap it with
     ``functools.partial(verify_token, static_token=..., registry_check=...)``.
 
+    The returned identity is never the presented key: a credential must
+    not reach the log line that records who called.
+
     :param presented: The raw key presented by the client.
     :param table: DynamoDB registry table name (optional). Used to build
         the default registry lookup when ``registry_check`` is not given.
@@ -165,28 +210,31 @@ def verify_token(
     :param region: AWS region for a default boto3 client (optional).
     :param dynamodb_client: Injected boto3 DynamoDB client (optional).
     :param registry_check: Lookup called with the SHA-256 *digest* of the
-        key (not the raw key) -- ``(key_sha256) -> bool`` -- replacing the
-        default :func:`key_active_in_registry` call. This is the seam for a
-        cached lookup: wrap :func:`key_active_in_registry` in a TTL cache
-        and pass it here. When given, ``table``/``region``/
+        key (not the raw key) -- ``(key_sha256) -> str | None`` --
+        replacing the default :func:`key_active_in_registry` call. This is
+        the seam for a cached lookup: wrap :func:`key_active_in_registry`
+        in a TTL cache and pass it here. When given, ``table``/``region``/
         ``dynamodb_client`` are not used.
-    :returns: True if the presented key is authorized.
+    :returns: The authorized client identity, else None. A static-token
+        match yields ``STATIC_TOKEN_CLIENT_ID`` so break-glass use is
+        distinguishable in a log from a registered client; a legacy
+        ``-> bool`` ``registry_check`` yields ``UNKNOWN_CLIENT_ID``.
     """
     if not presented:
-        return False
+        return None
     if static_token and secrets.compare_digest(presented, static_token):
-        return True
+        return STATIC_TOKEN_CLIENT_ID
     if registry_check is None and not table:
-        return False
+        return None
     try:
         if registry_check is not None:
-            return registry_check(hash_key(presented))
+            return _as_client_id(registry_check(hash_key(presented)))
         return key_active_in_registry(
             hash_key(presented), table=table, region=region,
             dynamodb_client=dynamodb_client)
     except Exception as exc:
         logger.warning('token registry lookup failed; denying (fail closed): %s', exc)
-        return False
+        return None
 
 
 def mint_key(
@@ -297,19 +345,19 @@ def list_clients(
 class ApiTokenMiddleware:
     """Raw ASGI middleware gating chosen path prefixes on a token.
 
-    HTTP requests under ``protected_prefixes`` must present a key
-    (``X-API-Key`` header, ``Authorization: Bearer``, or ``?key=``) that
-    ``verify`` authorizes; everything else passes through. ``verify`` is
-    any ``(presented) -> bool`` -- typically :func:`verify_token` bound to
-    its config::
+    HTTP requests under ``protected_prefixes`` must present a key -- in the
+    ``X-API-Key`` or ``Authorization: Bearer`` header -- that ``verify``
+    authorizes; everything else passes through. ``verify`` is any
+    ``(presented) -> str | None`` -- typically :func:`verify_token` bound
+    to its config::
 
         verify = functools.partial(
             verify_token, static_token=TOKEN, registry_check=cached_lookup)
         app.add_middleware(
             ApiTokenMiddleware, protected_prefixes=('/api/',), verify=verify)
 
-    The verifier runs in a worker thread and fails closed -- returning
-    False or raising yields a 401.
+    The verifier runs in a worker thread and fails closed -- returning a
+    falsy value or raising yields a 401.
 
     Raw ASGI, not ``BaseHTTPMiddleware``, so it never buffers a streaming
     body and depends on no web framework; only ``anyio`` is imported
@@ -317,9 +365,17 @@ class ApiTokenMiddleware:
     gated -- ``websocket`` connections pass through, so do not place a
     WebSocket endpoint under a protected prefix expecting it to be gated.
 
+    On success the authorized identity is published at
+    ``scope['state']['client_id']`` before the wrapped app runs, so a
+    downstream handler can attribute the request without re-reading the
+    credential. A legacy ``-> bool`` verifier yields ``UNKNOWN_CLIENT_ID``
+    there rather than a bare ``True``. A ``?key=`` query parameter is not
+    an accepted credential source; see the module docstring.
+
     :param app: The wrapped ASGI application.
     :param protected_prefixes: Path prefixes that require a token.
-    :param verify: ``(presented) -> bool`` authorizer.
+    :param verify: ``(presented) -> str | None`` authorizer returning the
+        identity.
     """
 
     def __init__(
@@ -327,7 +383,7 @@ class ApiTokenMiddleware:
         app: Any,
         *,
         protected_prefixes: Iterable[str],
-        verify: Callable[[str], bool],
+        verify: Callable[[str], str | None],
     ) -> None:
         """Wrap an ASGI app with the configured credential check."""
         self.app = app
@@ -343,16 +399,18 @@ class ApiTokenMiddleware:
             return
 
         presented = self._present_key(scope)
-        authorized = False
+        client_id = None
         if presented:
             try:
-                authorized = await anyio.to_thread.run_sync(self._verify, presented)
+                client_id = _as_client_id(
+                    await anyio.to_thread.run_sync(self._verify, presented))
             except Exception as exc:
                 logger.warning('authorization raised; denying (fail closed): %s', exc)
-        if not authorized:
+        if not client_id:
             await _send_unauthorized(send)
             return
 
+        scope.setdefault('state', {})['client_id'] = client_id
         await self.app(scope, receive, send)
 
     def _guards(self, scope: dict) -> bool:
@@ -363,7 +421,16 @@ class ApiTokenMiddleware:
 
     @staticmethod
     def _present_key(scope: dict) -> str | None:
-        """Pull the key from the X-API-Key, Bearer, or ?key= sources."""
+        """Pull the key from the X-API-Key or Bearer header, header-only.
+
+        The query string is never consulted. A credential in a URL is
+        written verbatim into proxy, load-balancer and web-server access
+        logs, so accepting ``?key=`` makes every request a disclosure.
+
+        :param scope: The ASGI HTTP connection scope.
+        :returns: The presented credential, or None when neither header
+            carries one.
+        """
         headers = {
             key.decode('latin-1').lower(): value.decode('latin-1')
             for key, value in scope.get('headers', [])
@@ -372,11 +439,8 @@ class ApiTokenMiddleware:
             return headers['x-api-key']
         authorization = headers.get('authorization', '')
         if authorization.lower().startswith('bearer '):
-            bearer = authorization[7:]
-            if bearer:
-                return bearer
-        query = parse_qs(scope.get('query_string', b'').decode('latin-1'))
-        return (query.get('key') or [None])[0]
+            return authorization[7:] or None
+        return None
 
 
 async def _send_unauthorized(send: Any) -> None:

{libb_util-0.0.44 → libb_util-0.0.45}/src/libb/webapp.py

@@ -213,14 +213,14 @@ def login_required(*, allowed_groups, session_accessor=None,
     return decorator
 
 
-def _extract_presented_key(allow_query_key: bool = False) -> str:
+def _extract_presented_key() -> str:
     """Pull a presented API key from the current Flask request.
 
-    Order: ``Authorization: Bearer <k>``, then ``X-Api-Key``, then the
-    ``?key=`` query arg when ``allow_query_key`` is set (off by default;
-    query strings leak into logs).
+    Order: ``Authorization: Bearer <k>``, then ``X-Api-Key``. The query
+    string is never consulted -- a credential in a URL is written verbatim
+    into proxy, load-balancer and web-server access logs, so accepting
+    ``?key=`` turns every request into a credential disclosure.
 
-    :param allow_query_key: Accept the key from the ?key query arg.
     :returns: The presented key, or '' if none.
     """
     header = flask.request.headers.get('Authorization', '')
@@ -229,13 +229,11 @@ def _extract_presented_key(allow_query_key: bool = False) -> str:
     api_key = flask.request.headers.get('X-Api-Key')
     if api_key:
         return api_key.strip()
-    if allow_query_key:
-        return (flask.request.args.get('key') or '').strip()
     return ''
 
 
 def token_required(*, table=None, static_token=None, region=None,
-                   dynamodb_client=None, allow_query_key=False):
+                   dynamodb_client=None):
     """Decorator: gate a Flask view on a registry token, failing closed.
 
     Extracts the key from the request (see :func:`_extract_presented_key`)
@@ -243,11 +241,15 @@ def token_required(*, table=None, static_token=None, region=None,
     unauthorized request gets a 401. Suited to machine endpoints
     (MCP / API) behind the standard Flask tier.
 
+    On success the authorized identity is published at ``flask.g.client_id``
+    before the view runs, so a view or an after-request logger can record
+    which client called without re-reading the credential. This mirrors
+    ``scope['state']['client_id']`` on the ASGI side.
+
     :param table: DynamoDB registry table name (optional).
     :param static_token: Constant-time break-glass token (optional).
     :param region: AWS region for a default boto3 client (optional).
     :param dynamodb_client: Injected boto3 DynamoDB client (optional).
-    :param allow_query_key: Accept the key from the ?key query arg.
     :returns: A view decorator.
     """
     from libb import tokenauth
@@ -255,11 +257,13 @@ def token_required(*, table=None, static_token=None, region=None,
     def decorator(view):
         @wraps(view)
         def token_required_fn(*args, **kwargs):
-            presented = _extract_presented_key(allow_query_key)
-            if not tokenauth.verify_token(
-                    presented, table=table, static_token=static_token,
-                    region=region, dynamodb_client=dynamodb_client):
+            presented = _extract_presented_key()
+            client_id = tokenauth.verify_token(
+                presented, table=table, static_token=static_token,
+                region=region, dynamodb_client=dynamodb_client)
+            if not client_id:
                 return flask.abort(401)
+            flask.g.client_id = client_id
             return view(*args, **kwargs)
 
         return token_required_fn