resourcey 0.0.1__py3-none-any.whl

resourcey/__init__.py

@@ -0,0 +1,4 @@
+"""resourcey — a resource-oriented Python web framework.
+
+Progressive enhancement with escape hatches to FastAPI, SQLAlchemy, and Alembic.
+"""

resourcey/__main__.py

@@ -0,0 +1,48 @@
+"""``python -m resourcey`` — the framework command dispatcher (issue #15).
+
+Apps are started with ``uvicorn <app_module>:app`` (the standard FastAPI path) —
+there is no ``resourcey run``, because the CLI cannot know the user's app module.
+What the dispatcher does provide is the background-task entry point::
+
+    python -m resourcey tasks list app:manifest
+    python -m resourcey tasks run  app:manifest [name]
+
+The framework does no ``.env`` loading of its own, so run it with the app's
+environment populated (e.g. ``uv run --env-file .env python -m resourcey …``).
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Sequence
+from typing import Any
+
+# Each subcommand maps to a callable taking the parsed Namespace and returning an
+# exit code. Populated lazily by ``_build_parser`` so importing the dispatcher
+# does not import every command's dependencies.
+_COMMANDS: dict[str, Callable[[Any], int]] = {}
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Dispatch a ``resourcey`` command. Returns a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    return int(_COMMANDS[args.command](args) or 0)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="resourcey", description="resourcey CLI.")
+    subparsers = parser.add_subparsers(dest="command")
+
+    from resourcey.tasks import cli as tasks_cli
+
+    tasks_cli.add_subparser(subparsers)
+    _COMMANDS["tasks"] = tasks_cli.run
+    return parser
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

resourcey/auth/auth_api_key.py

@@ -0,0 +1,237 @@
+"""API-key authentication (issue #118, re-expressed in #131).
+
+:class:`ApiKeyAuthenticator` is an
+:class:`~resourcey.auth.auth_principal.Authenticator`, so it plugs into
+:class:`~resourcey.auth.auth_authorized_dependency.AuthorizedDependencyBuilder`
+alongside every other method. It resolves a presented API key to a
+:class:`~resourcey.auth.auth_principal.Principal`:
+
+* a **DB-backed** key resolves to its owner (``principal.id == row.user_id``)
+  when the row carries one, so a policy can scope rows to the key's owner; a key
+  with no owner resolves to a **service** principal;
+* a **config-list** key resolves to a service principal (optionally named by
+  ``principal_id``).
+
+It holds the **inner** key resource (the DB-backed or config-list resource that
+exposes ``find_by_key``) and validates a presented key by hashing it and
+searching for that digest. It deliberately does not hold the exposed
+``ResourceView``, whose ``ViewService`` forwards only the eight standard actions.
+
+Contract:
+
+* two accepted headers — ``X-API-Key`` and, failing that,
+  ``Authorization: Bearer <key>``, both declared with ``Security`` so they appear
+  in the OpenAPI schema;
+* **fail-closed** — no key resource, or a key resource that matches nothing,
+  denies every request;
+* a **revoked** (``active=False``) or **expired** row denies the request;
+* the key check runs over a **fresh ctx**, so it always opens and closes its own
+  storage and never adopts the target resource's session.
+
+This module is part of ``resourcey.auth``; it imports only lower framework layers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Annotated, Any
+from uuid import UUID
+
+from fastapi import HTTPException, Request, Security, status
+from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer
+
+from resourcey.auth.auth_api_key_resource import hash_api_key
+from resourcey.auth.auth_principal import (
+    Authenticator,
+    AuthResult,
+    Principal,
+    PrincipalKind,
+    principal_is_active,
+)
+from resourcey.auth.auth_role import roles_from_credential
+
+API_KEY_HEADER_NAME = "X-API-Key"
+
+# ``Bearer`` is the canonical scheme for the ``Authorization`` fallback; the
+# dedicated ``X-API-Key`` header has no registered scheme, so the realm names it.
+API_KEY_CHALLENGE = 'Bearer realm="api-key"'
+
+# ``auto_error=False`` so the authenticator decides the response; declaring them
+# via ``Security`` keeps the schemes visible in the OpenAPI schema.
+_api_key_header = APIKeyHeader(
+    name=API_KEY_HEADER_NAME,
+    scheme_name="ApiKeyHeader",
+    auto_error=False,
+    description="API key sent as the `X-API-Key` header.",
+)
+
+_bearer_scheme = HTTPBearer(
+    scheme_name="ApiKeyBearer",
+    auto_error=False,
+    description="API key sent as `Authorization: Bearer <key>`.",
+)
+
+
+class ApiKeyAuthenticator(Authenticator):
+    """Authenticate a request against a stored or configured set of API keys.
+
+    ``key_resource`` is the **inner** key resource whose service exposes
+    ``find_by_key``; ``None`` fails closed. ``principal_id`` is the fixed id for
+    **config-list** keys (a DB row's owner always wins). ``user_resource`` is an
+    optional principal store the resolved principal is validated against.
+    """
+
+    key_resource: Any = None
+    principal_id: UUID | None = None
+    user_resource: Any = None
+
+    async def authenticate(self, request: Any) -> AuthResult:
+        """Resolve the request's API key (from either header) to an :class:`AuthResult`."""
+        presented = request.headers.get(API_KEY_HEADER_NAME)
+        if not presented:
+            authorization = request.headers.get("Authorization")
+            if authorization and authorization.lower().startswith("bearer "):
+                presented = authorization[len("bearer ") :].strip()
+        if not presented:
+            return AuthResult.absent()
+        row = await self.lookup_api_key(presented)
+        if row is None:
+            return AuthResult.invalid()
+        principal = self._principal_for(row)
+        if not await self._principal_is_active(principal):
+            return AuthResult.invalid()
+        return AuthResult.authenticated(principal)
+
+    def dependency(self) -> Callable[..., Any]:
+        """A FastAPI dependency declaring the two key schemes and returning the result.
+
+        Declares ``X-API-Key`` / ``Bearer`` via ``Security`` so both appear in the
+        OpenAPI schema, then defers to :meth:`authenticate` for the decision.
+        """
+        from resourcey.auth.auth_principal import resolve_auth_result
+
+        authenticator = self
+
+        async def dependency(
+            request: Request,
+            x_api_key: Annotated[str | None, Security(_api_key_header)] = None,
+            bearer: Annotated[HTTPAuthorizationCredentials | None, Security(_bearer_scheme)] = None,
+        ) -> AuthResult:
+            return await resolve_auth_result(request, authenticator)
+
+        dependency.__name__ = "api_key_authenticator_dependency"
+        return dependency
+
+    def challenge(self) -> str:
+        """The API-key realm, so a 401 names the scheme (``Bearer realm="api-key"``)."""
+        return API_KEY_CHALLENGE
+
+    async def api_key_dependency(
+        self,
+        x_api_key: Annotated[str | None, Security(_api_key_header)] = None,
+        bearer: Annotated[HTTPAuthorizationCredentials | None, Security(_bearer_scheme)] = None,
+    ) -> Principal:
+        """A standalone FastAPI dependency: 401 unless a valid key is presented.
+
+        For a custom router or endpoint that is not secured by the builder.
+        """
+        presented = x_api_key
+        if presented is None and bearer is not None:
+            presented = bearer.credentials
+        row = await self.lookup_api_key(presented) if presented else None
+        if row is None:
+            raise _reject()
+        principal = self._principal_for(row)
+        # The same store check as ``authenticate``, so a custom router cannot
+        # accept a key whose principal is missing or disabled.
+        if not await self._principal_is_active(principal):
+            raise _reject()
+        return principal
+
+    async def lookup_api_key(self, presented: str) -> Any | None:
+        """The stored key entry for ``presented``, or ``None`` (fail-closed).
+
+        The value is hashed (SHA-256) and the digest searched for; the plaintext is
+        never compared. An **inactive** or **expired** row also yields ``None``.
+        The lookup runs over a **fresh, call-scoped ctx**, so the key service never
+        adopts the target resource's session.
+        """
+        if not presented or self.key_resource is None:
+            return None
+        service = await self.key_resource.get_service({})
+        async with service:
+            find = getattr(service, "find_by_key", None)
+            if find is None:  # pragma: no cover - the resource is validated upstream
+                return None
+            row = await find(hash_api_key(presented))
+            if row is None:
+                return None
+            return row if _key_is_live(row) else None
+
+    def _principal_for(self, row: Any) -> Principal:
+        """The principal a matched key row resolves to.
+
+        A DB row's owner wins when present; otherwise the row's own
+        ``principal_id`` names a service principal, falling back to the
+        authenticator's fixed :attr:`principal_id`. The row's
+        credential-carried ``roles`` are populated with no extra lookup.
+        """
+        owner = getattr(row, "user_id", None)
+        roles = roles_from_credential(getattr(row, "roles", None))
+        if owner is not None:
+            return Principal(id=owner, kind=PrincipalKind.USER, roles=roles)
+        # A present-but-unparseable id degrades to ``None`` rather than adopting
+        # the shared fixed principal, so a malformed binding cannot grant
+        # another principal's scope.
+        raw_principal_id = getattr(row, "principal_id", None)
+        principal_id = (
+            _as_uuid(raw_principal_id) if raw_principal_id is not None else self.principal_id
+        )
+        return Principal(id=principal_id, kind=PrincipalKind.SERVICE, roles=roles)
+
+    async def _principal_is_active(self, principal: Principal) -> bool:
+        """Whether ``principal`` is a live user in the configured principal store.
+
+        Delegates to the shared check so the API-key and OAuth methods enforce the
+        identical store rule.
+        """
+        return await principal_is_active(self.user_resource, principal)
+
+
+def _reject() -> HTTPException:
+    """The 401 raised when a presented key is missing, invalid, or not a live principal."""
+    return HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or missing API key.",
+        headers={"WWW-Authenticate": API_KEY_CHALLENGE},
+    )
+
+
+def _as_uuid(value: Any) -> UUID | None:
+    """Coerce a stored principal id (a string in config) to a ``UUID``, or ``None``."""
+    if value is None or isinstance(value, UUID):
+        return value
+    try:
+        return UUID(str(value))
+    except ValueError:
+        return None
+
+
+def _key_is_live(row: Any, *, now: datetime | None = None) -> bool:
+    """Whether a stored key row is usable: ``active`` and not past ``expires_at``.
+
+    A row that does not carry these columns (the config-list entry type) is
+    treated as live.
+    """
+    active = getattr(row, "active", None)
+    if active is not None and not active:
+        return False
+    expires_at = getattr(row, "expires_at", None)
+    if expires_at is not None:
+        current = now or datetime.now(UTC)
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=UTC)
+        if expires_at <= current:
+            return False
+    return True

resourcey/auth/auth_api_key_resource.py

@@ -0,0 +1,251 @@
+"""The API-key resources and key-generation helpers (issue #118).
+
+Two key sources, declared once with **full storage truth** and exposed through a
+narrowing :class:`~resourcey.view.resource_view.ResourceView`:
+
+* the **DB-backed** resource — an ORM ``ApiKey`` row minted / revoked through the
+  ordinary REST surface;
+* the **config-list** resource — a read-only :class:`ListResource` built from
+  :class:`~resourcey.auth.auth_config.ApiKeysConfig`.
+
+Both store the key **only as a SHA-256 digest**, declared as
+:class:`~pydantic.SecretStr` so the model layer treats it as a secret even though
+the stored value is already a digest. A presented key is validated by hashing it
+and searching for that hash — never through the public query surface, which the
+view closes.
+
+The raw key is disclosed exactly once, in the ``201`` create response, through
+the ``expose_secrets`` serialization context. ``in_create_request`` must be
+``False``: otherwise a client could supply the digest the lookup would match.
+
+This module is part of ``resourcey.auth``; it imports only lower framework layers.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import string
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, SecretStr
+from sqlalchemy import JSON, Boolean, DateTime, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from resourcey.auth.auth_config import ApiKeysConfig
+from resourcey.core.resource import Resource
+from resourcey.list.list_resource import ListResource
+from resourcey.sql.sql_resource import SqlResource
+from resourcey.view.resource_view import ResourceView
+
+# The name of the secret-bearing field, shared with the service that reveals it.
+KEY_FIELD = "key"
+
+API_KEY_RANDOM_BITS = 256
+
+# A prefix that makes a leaked key recognisable to secret scanners.
+API_KEY_FORMAT = "rsk_{secret}"
+
+_BASE36_ALPHABET = string.digits + string.ascii_lowercase
+
+# ceil(API_KEY_RANDOM_BITS / log2(36)); padding keeps a key's length constant.
+_BASE36_WIDTH = 50
+
+# SHA-256 hex is 64 characters.
+_KEY_HASH_LENGTH = 64
+
+# The key is never read, searched, updated, or client-supplied — only the
+# create response reveals it.
+KEY_EXPOSED: dict[str, dict[str, Any]] = {
+    KEY_FIELD: {
+        "in_create_request": False,
+        "in_create_response": True,
+        "in_read_response": False,
+        "in_search_response": False,
+        "in_update_request": False,
+        "in_update_response": False,
+    }
+}
+
+# The read-only variant: the key and the internal credential bindings
+# (``principal_id`` / ``roles``) are hidden from every response and the query
+# surface.
+KEY_QUERY_SURFACE_HIDDEN: dict[str, dict[str, Any]] = {
+    KEY_FIELD: {"in_read_response": False, "in_search_response": False},
+    "principal_id": {"in_read_response": False, "in_search_response": False},
+    "roles": {"in_read_response": False, "in_search_response": False},
+}
+
+# The DB-backed view is the full key surface: only the secret ``key`` is
+# projected away, so ``roles`` stays writable. That makes this resource a
+# **privilege-assignment surface** — access must be restricted to administrators.
+STORED_KEY_EXPOSED: dict[str, dict[str, Any]] = dict(KEY_EXPOSED)
+
+
+def encode_base36(value: int, width: int) -> str:
+    """Render ``value`` in base 36, zero-padded to ``width`` characters."""
+    digits: list[str] = []
+    while value > 0:
+        value, remainder = divmod(value, 36)
+        digits.append(_BASE36_ALPHABET[remainder])
+    return "".join(reversed(digits)).rjust(width, _BASE36_ALPHABET[0])
+
+
+def generate_api_key(key_format: str = API_KEY_FORMAT) -> str:
+    """Mint a key: a fresh random secret rendered into ``key_format``.
+
+    The secret is :data:`API_KEY_RANDOM_BITS` bits from a CSPRNG, so keys are
+    unguessable and collisions are not a practical concern.
+    """
+    secret = int.from_bytes(secrets.token_bytes(API_KEY_RANDOM_BITS // 8), "big")
+    return key_format.format(secret=encode_base36(secret, _BASE36_WIDTH))
+
+
+def hash_api_key(raw: str) -> str:
+    """The SHA-256 hex digest of a raw key — the value stored at rest.
+
+    A presented key is hashed and the digest looked up, so neither the table nor
+    the config list holds a usable credential.
+    """
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def utc_now() -> datetime:
+    """Default factory for the ``created_at`` / ``updated_at`` columns."""
+    return datetime.now(UTC)
+
+
+class ApiKeyBase(DeclarativeBase):
+    """The declarative base owning the ``api_keys`` table (an app points Alembic at it)."""
+
+
+class ApiKey(ApiKeyBase):
+    """An API key stored as a row, mintable and revocable at runtime.
+
+    The ORM attribute is ``key``; the DB column is ``key_hash`` and stores the
+    SHA-256 digest, declared as :class:`~pydantic.SecretStr` so the derived DTO
+    field is a secret. The create response is the only place the key is
+    disclosed, and even there it is the *raw* minted value.
+    """
+
+    __tablename__ = "api_keys"
+
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    key: Mapped[SecretStr] = mapped_column(
+        "key_hash", String(_KEY_HASH_LENGTH), nullable=False, unique=True, index=True
+    )
+    user_id: Mapped[UUID | None] = mapped_column(nullable=True, index=True)
+    roles: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    active: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True, server_default="true"
+    )
+    issued_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=utc_now, onupdate=utc_now
+    )
+
+
+class StoredApiKeyResource(SqlResource[Any, Any]):
+    """The DB-backed key resource: the ``ApiKey`` model, with ``find_by_key``.
+
+    Builds a ``StoredApiKeyService`` (which adds ``find_by_key`` and the
+    one-time reveal). The import is deferred to :meth:`make_service` to avoid a
+    module cycle.
+    """
+
+    def make_service(self, ctx: Any, session_factory: Any) -> Any:
+        from resourcey.auth.auth_api_key_service import StoredApiKeyService
+
+        return StoredApiKeyService(self, ctx, session_factory)
+
+
+class ConfigApiKeyResource(ListResource[Any, Any]):
+    """The read-only config key resource, with ``find_by_key``."""
+
+    def make_service(self, ctx: Any, items: list[Any]) -> Any:
+        from resourcey.auth.auth_api_key_service import ConfigApiKeyService
+
+        return ConfigApiKeyService(self, ctx, items)
+
+
+def stored_api_key_resource(
+    *,
+    session_factory: Any = None,
+    session_manager: Any = None,
+    name: str | None = None,
+    path: str | None = None,
+) -> Resource[Any, Any]:
+    """The DB-backed key resource: the ``ApiKey`` ORM model with full storage truth.
+
+    This is the **inner** resource the authenticator holds to reach
+    ``find_by_key``; register :func:`stored_api_key_view` in the manifest, not this.
+    """
+    return StoredApiKeyResource(
+        ApiKey,
+        session_factory=session_factory,
+        session_manager=session_manager,
+        name=name,
+        path=path or "api-keys",
+    )
+
+
+def stored_api_key_view(inner: Resource[Any, Any]) -> ResourceView[Any, Any]:
+    """The exposed view over a DB-backed key resource (the one-time reveal)."""
+    return ResourceView(inner, exposed_field_overrides=STORED_KEY_EXPOSED)
+
+
+class ConfigApiKey(BaseModel):
+    """A served config key: the identifier, the label, the digest, and its roles.
+
+    Only ``id`` / ``name`` are ever exposed; ``key`` holds the digest and is
+    hidden by the read-hiding view, so the authenticator can search it but never
+    read it.
+    """
+
+    id: str
+    name: str | None = None
+    key: SecretStr
+    principal_id: str | None = None
+    roles: list[str] = Field(default_factory=list)
+
+
+def config_api_key_models(config: ApiKeysConfig) -> list[ConfigApiKey]:
+    """The served config entries, with each plaintext key hashed on load.
+
+    The plaintext is read once, hashed, and not retained.
+    """
+    return [
+        ConfigApiKey(
+            id=entry.id,
+            name=entry.name,
+            key=SecretStr(hash_api_key(entry.key.get_secret_value())),
+            principal_id=entry.principal_id,
+            roles=list(entry.roles),
+        )
+        for entry in config.api_keys
+    ]
+
+
+def config_api_key_resource(
+    config: ApiKeysConfig, *, path: str | None = None
+) -> ConfigApiKeyResource:
+    """The read-only, config-backed key resource over the hashed entries."""
+    return ConfigApiKeyResource(
+        config_api_key_models(config),
+        model=ConfigApiKey,
+        path=path or "api-keys",
+    )
+
+
+def config_api_key_view(inner: Resource[Any, Any]) -> ResourceView[Any, Any]:
+    """The exposed view over a config-list key resource (read-only, key hidden).
+
+    Uses :data:`KEY_QUERY_SURFACE_HIDDEN` (not :data:`KEY_EXPOSED`): the config
+    list is read-only, so there is no create route to reveal anything.
+    """
+    return ResourceView(inner, exposed_field_overrides=KEY_QUERY_SURFACE_HIDDEN)

resourcey/auth/auth_api_key_service.py

@@ -0,0 +1,94 @@
+"""The services backing the two API-key resources (issue #118).
+
+Both expose the same lookup seam a presented key is validated through::
+
+    async def find_by_key(self, key_hash: str) -> Any | None
+
+``key_hash`` is the SHA-256 digest of the presented key. The lookup is a
+dedicated method, never a :class:`~resourcey.util.search_filter.SearchFilter` —
+the public query surface is closed over the key, so a guess-confirmation oracle
+over the digest must not be reachable through ``?key__eq=``.
+
+:class:`StoredApiKeyService` mints a raw key, stores its digest, and reveals the
+raw value once through the ``expose_secrets`` serialization context.
+:class:`ConfigApiKeyService` looks the digest up in the in-process list,
+comparing with :func:`secrets.compare_digest`.
+
+This module is part of ``resourcey.auth``; it imports only lower framework layers.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import SecretStr
+
+from resourcey.auth.auth_api_key_resource import KEY_FIELD, generate_api_key, hash_api_key
+from resourcey.list.list_service import ListService
+from resourcey.sql.sql_service import SqlService
+
+# The context that makes the create response disclose the freshly minted key.
+EXPOSE_SECRETS: dict[str, Any] = {"expose_secrets": True}
+
+
+@runtime_checkable
+class SupportsFindByKey(Protocol):
+    """A service that can look a presented key's digest up without the query surface."""
+
+    async def find_by_key(self, key_hash: str) -> Any | None:
+        """Return the entry whose stored digest is ``key_hash``, or ``None``."""
+        ...
+
+
+class StoredApiKeyService(SqlService[Any, Any]):
+    """A :class:`SqlService` whose ``create`` mints, stores a digest, and reveals.
+
+    The stored value is always the SHA-256 digest of a freshly minted key; the
+    raw key is disclosed exactly once, in the create response.
+    """
+
+    async def create(self, payload: Any) -> Any:
+        """Mint a key, persist its digest, and return the DTO with the raw key.
+
+        This is the only response that carries the raw value — a caller that
+        loses it must mint a replacement.
+        """
+        raw = generate_api_key()
+        stored = payload.model_copy(update={KEY_FIELD: SecretStr(hash_api_key(raw))})
+        created = await super().create(stored)
+        self.set_serialization_context(EXPOSE_SECRETS)
+        return created.model_copy(update={KEY_FIELD: SecretStr(raw)})
+
+    async def find_by_key(self, key_hash: str) -> Any | None:
+        """Look the digest up by indexed equality; ``None`` when absent.
+
+        A direct ``WHERE key_hash = :digest`` through the resource's escape
+        hatch, never a ``SearchFilter``, so it is not reachable from the public
+        query surface.
+        """
+        session = self._active_session()
+        column = self._resource.table.c[self._resource.get_column_name(KEY_FIELD)]
+        statement = column.table.select().where(column == key_hash)
+        row = (await session.execute(statement)).mappings().first()
+        if row is None:
+            return None
+        return self._to_dto(row)
+
+
+class ConfigApiKeyService(ListService[Any, Any]):
+    """A :class:`ListService` that can look a digest up in the served list."""
+
+    async def find_by_key(self, key_hash: str) -> Any | None:
+        """Return the entry whose stored digest equals ``key_hash``, or ``None``.
+
+        The comparison is constant-time, so a shared prefix does not leak on timing.
+        """
+        self._require_entered()
+        candidate = key_hash.encode()
+        for item in self._items:
+            stored = getattr(item, KEY_FIELD, None)
+            raw = stored.get_secret_value() if isinstance(stored, SecretStr) else stored
+            if raw is not None and secrets.compare_digest(candidate, str(raw).encode()):
+                return item
+        return None