internetdata 2.5.0__tar.gz → 2.6.0__tar.gz

{internetdata-2.5.0 → internetdata-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: internetdata
-Version: 2.5.0
+Version: 2.6.0
 Summary: Official Python client library for the InternetData API. Download and verify licensed IP datasets.
 Project-URL: Homepage, https://internetdata.io
 Project-URL: Documentation, https://docs.internetdata.io
@@ -203,6 +203,26 @@ client = InternetData(tokens.apikey)
 
 A refusal raises `OauthAccessDeniedError` and a code that ran out raises `OauthExpiredTokenError`, and client IDs are issued on request from support@internetdata.io. `client.oauth.revoke("your-client-id", tokens.refresh_token)` signs the machine out.
 
+### Sign in with OAuth (authorization code)
+
+An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:
+
+```python
+from internetdata import InternetData
+
+signin = InternetData()
+redirect_uri = "http://127.0.0.1:8765/callback"
+pkce = signin.oauth.create_pkce()
+
+url = signin.oauth.authorization_url(
+    "your-client-id", redirect_uri, pkce.challenge, scope="apikeys.use", state="your-state"
+)
+# Open url in the browser. Its redirect to redirect_uri carries code and state.
+tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.verifier, redirect_uri)
+```
+
+Check that `state` came back as you sent it before you exchange `code`, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so `tokens.apikey` stays `None`.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/internetdata for more.

{internetdata-2.5.0 → internetdata-2.6.0}/README.md

@@ -169,6 +169,26 @@ client = InternetData(tokens.apikey)
 
 A refusal raises `OauthAccessDeniedError` and a code that ran out raises `OauthExpiredTokenError`, and client IDs are issued on request from support@internetdata.io. `client.oauth.revoke("your-client-id", tokens.refresh_token)` signs the machine out.
 
+### Sign in with OAuth (authorization code)
+
+An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:
+
+```python
+from internetdata import InternetData
+
+signin = InternetData()
+redirect_uri = "http://127.0.0.1:8765/callback"
+pkce = signin.oauth.create_pkce()
+
+url = signin.oauth.authorization_url(
+    "your-client-id", redirect_uri, pkce.challenge, scope="apikeys.use", state="your-state"
+)
+# Open url in the browser. Its redirect to redirect_uri carries code and state.
+tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.verifier, redirect_uri)
+```
+
+Check that `state` came back as you sent it before you exchange `code`, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so `tokens.apikey` stays `None`.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/internetdata for more.

{internetdata-2.5.0 → internetdata-2.6.0}/src/internetdata/__init__.py

@@ -34,11 +34,12 @@ from .models import (
     MetadataColumn,
     OauthMetadata,
     Outcome,
+    Pkce,
     Standing,
     TokenResponse,
 )
 
-__version__ = "2.5.0"
+__version__ = "2.6.0"
 
 __all__ = [
     "DATABASE_FORMATS",
@@ -66,6 +67,7 @@ __all__ = [
     "OauthExpiredTokenError",
     "OauthMetadata",
     "Outcome",
+    "Pkce",
     "Standing",
     "TokenResponse",
     "__version__",

{internetdata-2.5.0 → internetdata-2.6.0}/src/internetdata/_core.py

@@ -4,24 +4,28 @@ each attempt, response unwrapping, and the retry policy."""
 from __future__ import annotations
 
 import asyncio
+import base64
 import contextlib
 import contextvars
+import hashlib
 import json
 import math
 import os
+import secrets
 import threading
 import time
 from collections.abc import Awaitable, Callable, Iterator
 from pathlib import Path
 from types import ModuleType
 from typing import IO, Any, TypeVar, cast
+from urllib.parse import quote
 
 import httpx
 
 from ._generated.client import AuthenticatedClient, Client
 from ._generated.types import Response
 from .errors import InternetDataError, error_from_response, oauth_error_from
-from .models import Database, Download, to_database, to_download
+from .models import Database, Download, Pkce, to_database, to_download
 
 DEFAULT_BASE_URL = "https://internetdata.io"
 DEFAULT_RETRIES = 2
@@ -32,6 +36,7 @@ OAUTH_METADATA_PATH = "/.well-known/oauth-authorization-server"
 OAUTH_DEVICE_AUTHORIZATION_PATH = "/oauth/device_authorization"
 OAUTH_TOKEN_PATH = "/oauth/token"
 OAUTH_REVOKE_PATH = "/oauth/revoke"
+OAUTH_AUTHORIZE_PATH = "/oauth/authorize"
 DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
 
 # One chunk of a transfer, and therefore the ceiling on what a download of any size
@@ -337,6 +342,58 @@ async def oauth_request_async(
     return oauth_checked(await exchange_async(http, req, bound))
 
 
+def authorization_url(
+    base_url: str,
+    client_id: str,
+    redirect_uri: str,
+    code_challenge: str,
+    optional: dict[str, str | None],
+) -> str:
+    """The authorization code flow's URL, built with no request: the five parameters every
+    one carries, then `scope`, `state` and `resource` when given and not empty.
+
+    Each value is percent-encoded over UTF-8 with only A-Z a-z 0-9 - . _ ~ left literal, so
+    a space is %20 and never +. A required value that is empty, or has no UTF-8 (a lone
+    surrogate), is refused.
+    """
+    required = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "code_challenge": code_challenge,
+    }
+    for name, value in required.items():
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{name} must be a non-empty string, not {value!r}")
+    params = [
+        ("response_type", "code"),
+        *required.items(),
+        ("code_challenge_method", "S256"),
+        *((name, value) for name, value in optional.items() if value),
+    ]
+    encoded = []
+    for name, value in params:
+        try:
+            encoded.append(f"{name}={quote(value, safe='')}")
+        except UnicodeEncodeError as exc:
+            raise ValueError(f"{name} has no UTF-8 to send: {value!r}") from exc
+    return f"{base_url.rstrip('/')}{OAUTH_AUTHORIZE_PATH}?{'&'.join(encoded)}"
+
+
+def create_pkce() -> Pkce:
+    """A fresh PKCE pair, from 32 bytes of the system's secure random source."""
+    verifier = _base64url(secrets.token_bytes(32))
+    return Pkce(verifier=verifier, challenge=pkce_challenge(verifier))
+
+
+def pkce_challenge(verifier: str) -> str:
+    """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
+    return _base64url(hashlib.sha256(verifier.encode("utf-8")).digest())
+
+
+def _base64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
 def oauth_checked(res: httpx.Response) -> httpx.Response:
     """A 2xx as it came, or the failure it describes.
 

{internetdata-2.5.0 → internetdata-2.6.0}/src/internetdata/aio.py

@@ -30,16 +30,19 @@ from ._core import (
     AsyncClock,
     as_error,
     assert_whole_transfer,
+    authorization_url,
     build_async_transfer_client,
     build_client,
     check_timeout,
     checksums_of,
+    create_pkce,
     databases_of,
     downloads_of,
     oauth_body,
     oauth_request_async,
     parse_body,
     part_file,
+    pkce_challenge,
     redirect_location,
     request_async,
     retry_delay,
@@ -63,6 +66,7 @@ from .models import (
     Download,
     Format,
     OauthMetadata,
+    Pkce,
     TokenResponse,
     to_device_authorization,
     to_metadata,
@@ -99,6 +103,7 @@ class AsyncInternetData:
     ) -> None:
         timeout = check_timeout(timeout)
         self._client = build_client(api_key, base_url, timeout, transport)
+        self._base_url = base_url
         self._transfer = build_async_transfer_client(timeout, transport)
         self._retries = retries
         self._timeout = timeout
@@ -381,6 +386,54 @@ class AsyncOauthApi:
         }
         return await self._exchange(form, timeout)
 
+    async def exchange_authorization_code(
+        self,
+        client_id: str,
+        code: str,
+        code_verifier: str,
+        redirect_uri: str,
+        *,
+        timeout: float | None = None,
+    ) -> TokenResponse:
+        """Trade a redirect's code for tokens, once; see `OauthApi.exchange_authorization_code`."""
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "code_verifier": code_verifier,
+        }
+        return await self._exchange(form, timeout)
+
+    def authorization_url(
+        self,
+        client_id: str,
+        redirect_uri: str,
+        code_challenge: str,
+        *,
+        scope: str | None = None,
+        state: str | None = None,
+        resource: str | None = None,
+    ) -> str:
+        """The authorization code flow's URL, made with no request; see
+        `OauthApi.authorization_url`.
+        """
+        return authorization_url(
+            self._owner._base_url,
+            client_id,
+            redirect_uri,
+            code_challenge,
+            {"scope": scope, "state": state, "resource": resource},
+        )
+
+    def create_pkce(self) -> Pkce:
+        """A fresh PKCE pair for one sign-in, from the system's secure random source."""
+        return create_pkce()
+
+    def pkce_challenge(self, verifier: str) -> str:
+        """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
+        return pkce_challenge(verifier)
+
     async def revoke(self, client_id: str, token: str, *, timeout: float | None = None) -> None:
         """End a token; revoking the refresh token signs the machine out."""
 

{internetdata-2.5.0 → internetdata-2.6.0}/src/internetdata/client.py

@@ -25,16 +25,19 @@ from ._core import (
     Clock,
     as_error,
     assert_whole_transfer,
+    authorization_url,
     build_client,
     build_transfer_client,
     check_timeout,
     checksums_of,
+    create_pkce,
     databases_of,
     downloads_of,
     oauth_body,
     oauth_request,
     parse_body,
     part_file,
+    pkce_challenge,
     redirect_location,
     request,
     retry_delay,
@@ -58,6 +61,7 @@ from .models import (
     Download,
     Format,
     OauthMetadata,
+    Pkce,
     TokenResponse,
     to_device_authorization,
     to_metadata,
@@ -107,6 +111,7 @@ class InternetData:
     ) -> None:
         timeout = check_timeout(timeout)
         self._client = build_client(api_key, base_url, timeout, transport)
+        self._base_url = base_url
         self._transfer = build_transfer_client(timeout, transport)
         self._retries = retries
         self._timeout = timeout
@@ -339,7 +344,8 @@ class DatabaseApi:
 
 class OauthApi:
     """Signing a person in with the OAuth device flow, so a program running on their own
-    machine can be handed one of their API keys instead of asking them to paste it.
+    machine can be handed one of their API keys instead of asking them to paste it, or
+    through a browser redirect with the authorization code flow.
 
     No request here carries this client's API key, and none needs one: build the client
     with no key to sign in, then a second one with the key the sign-in hands over. The
@@ -412,6 +418,58 @@ class OauthApi:
         }
         return self._exchange(form, timeout)
 
+    def exchange_authorization_code(
+        self,
+        client_id: str,
+        code: str,
+        code_verifier: str,
+        redirect_uri: str,
+        *,
+        timeout: float | None = None,
+    ) -> TokenResponse:
+        """Trade the `code` a sign-in's redirect brought back for tokens, once: the server
+        spends the code on first read, before it checks `code_verifier`, the PKCE verifier
+        whose challenge went into the authorization URL. `redirect_uri` is that URL's, exactly.
+        """
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "code_verifier": code_verifier,
+        }
+        return self._exchange(form, timeout)
+
+    def authorization_url(
+        self,
+        client_id: str,
+        redirect_uri: str,
+        code_challenge: str,
+        *,
+        scope: str | None = None,
+        state: str | None = None,
+        resource: str | None = None,
+    ) -> str:
+        """The URL to open in the person's browser for the authorization code flow. Makes no
+        request. Once they decide, the server redirects to `redirect_uri` with a `code` for
+        `exchange_authorization_code` (and `state`, when one was given), or with an `error`.
+        """
+        return authorization_url(
+            self._owner._base_url,
+            client_id,
+            redirect_uri,
+            code_challenge,
+            {"scope": scope, "state": state, "resource": resource},
+        )
+
+    def create_pkce(self) -> Pkce:
+        """A fresh PKCE pair for one sign-in, from the system's secure random source."""
+        return create_pkce()
+
+    def pkce_challenge(self, verifier: str) -> str:
+        """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
+        return pkce_challenge(verifier)
+
     def revoke(self, client_id: str, token: str, *, timeout: float | None = None) -> None:
         """End a token. A refresh token ends the whole sign-in and every token it issued, so
         revoking it is how a program signs the machine out."""

{internetdata-2.5.0 → internetdata-2.6.0}/src/internetdata/models.py

@@ -278,6 +278,17 @@ class DeviceAuthorization:
     verification_uri_complete: str | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class Pkce:
+    """One sign-in's PKCE pair: `challenge` goes in the authorization URL, `verifier` to the
+    code exchange. The verifier is left out of the repr, so logging the pair does not leak it.
+    """
+
+    verifier: str = field(repr=False)
+    challenge: str
+    method: Literal["S256"] = "S256"
+
+
 @dataclass(frozen=True, slots=True)
 class TokenResponse:
     """What a token exchange answers.

{internetdata-2.5.0 → internetdata-2.6.0}/tests/helpers.py

@@ -139,9 +139,26 @@ class OauthAdapter:
     def exchange_refresh_token(self, client_id: str, refresh_token: str, **kwargs: Any) -> Any:
         return self._call("exchange_refresh_token", client_id, refresh_token, **kwargs)
 
+    def exchange_authorization_code(
+        self, client_id: str, code: str, code_verifier: str, redirect_uri: str, **kwargs: Any
+    ) -> Any:
+        return self._call(
+            "exchange_authorization_code", client_id, code, code_verifier, redirect_uri, **kwargs
+        )
+
     def revoke(self, client_id: str, token: str, **kwargs: Any) -> Any:
         return self._call("revoke", client_id, token, **kwargs)
 
+    # These three make no request, so they are plain methods on both clients.
+    def authorization_url(self, *args: Any, **kwargs: Any) -> Any:
+        return self._client.oauth.authorization_url(*args, **kwargs)
+
+    def create_pkce(self) -> Any:
+        return self._client.oauth.create_pkce()
+
+    def pkce_challenge(self, verifier: str) -> Any:
+        return self._client.oauth.pkce_challenge(verifier)
+
     def poll_device_token(self, client_id: str, device: Any, **kwargs: Any) -> Any:
         return self._call("poll_device_token", client_id, device, **kwargs)
 

{internetdata-2.5.0 → internetdata-2.6.0}/tests/test_oauth.py

@@ -1,6 +1,6 @@
 """The `oauth` accessor against the shared corpus's oauth section, on both clients.
 
-Nothing here reads `oauth.deferred`: those operations are not in this release. Every call
+The authorization code flow's vectors, under `oauth.deferred`, are read here too. Every call
 under test runs through `settle`, so a loop that never ends fails its test instead of
 hanging the suite.
 """
@@ -8,6 +8,7 @@ hanging the suite.
 from __future__ import annotations
 
 import asyncio
+import re
 import time
 import urllib.parse
 from collections.abc import Iterator
@@ -82,7 +83,9 @@ def test_no_oauth_request_carries_the_api_key(make_client: ClientFactory) -> Non
     outcome = settle(lambda: _every_operation(client.oauth), bound)
 
     assert outcome is None, f"settled with {outcome!r}"
-    assert len(stub.requests) == 6
+    assert len(stub.requests) == 7
+    url = client.oauth.authorization_url("internetdata-cli", "http://127.0.0.1/cb", "c" * 43)
+    assert key not in url, "the authorization URL carried the API key"
     for req in stub.requests:
         label = f"{req.method} {req.url.path}"
         for name in case["forbiddenHeaders"]:
@@ -98,7 +101,9 @@ def test_no_oauth_request_carries_the_api_key(make_client: ClientFactory) -> Non
     assert stub.requests[-1].headers["authorization"] == f"Bearer {key}"
 
 
-@pytest.mark.parametrize("case", CORPUS["forms"]["cases"], ids=lambda case: case["name"])
+@pytest.mark.parametrize(
+    "case", CORPUS["forms"]["cases"] + CORPUS["deferred"]["forms"], ids=lambda case: case["name"]
+)
 def test_each_operation_requests_its_endpoint_with_exactly_its_form_fields(
     make_client: ClientFactory, case: dict[str, Any]
 ) -> None:
@@ -244,7 +249,11 @@ def test_a_failed_answer_is_an_oauth_refusal_only_when_it_is_one(
     _assert_outcome(outcome, case["expect"], case["name"])
 
 
-@pytest.mark.parametrize("case", CORPUS["retries"]["cases"], ids=lambda case: case["name"])
+@pytest.mark.parametrize(
+    "case",
+    CORPUS["retries"]["cases"] + CORPUS["deferred"]["retries"],
+    ids=lambda case: case["name"],
+)
 def test_only_what_consumes_nothing_is_retried(
     make_client: ClientFactory, case: dict[str, Any]
 ) -> None:
@@ -319,11 +328,68 @@ def test_cancelling_a_poll_during_its_first_wait_ends_it_at_once() -> None:
     assert stub.requests == [], "no request after the cancel"
 
 
+@pytest.mark.parametrize(
+    "case", CORPUS["deferred"]["authorizationUrl"], ids=lambda case: case["name"]
+)
+def test_an_authorization_url_is_built_exactly_as_the_corpus_spells_it(
+    make_client: ClientFactory, case: dict[str, Any]
+) -> None:
+    stub = OauthStub([{"status": 200, "body": EVERY_REQUIRED_MEMBER}], LoopBound())
+    client = make_client(base_url=case["baseUrl"], transport=stub.transport)
+
+    url = client.oauth.authorization_url(
+        case["clientId"],
+        case["redirectUri"],
+        case["codeChallenge"],
+        scope=case.get("scope"),
+        state=case.get("state"),
+        resource=case.get("resource"),
+    )
+
+    assert url == case["expect"]
+    assert stub.requests == [], "requests sent"
+
+
+def test_an_authorization_url_leaves_out_an_empty_option_and_refuses_an_empty_value(
+    make_client: ClientFactory,
+) -> None:
+    case = CORPUS["deferred"]["authorizationUrl"][0]
+    oauth = make_client(base_url=BASE_URL).oauth
+    args = (case["clientId"], case["redirectUri"], case["codeChallenge"])
+
+    url = oauth.authorization_url(*args, scope="", state="", resource="")
+
+    assert url == case["expect"].replace(case["baseUrl"], BASE_URL)
+    with pytest.raises(ValueError, match="client_id"):
+        oauth.authorization_url("", case["redirectUri"], case["codeChallenge"])
+    with pytest.raises(ValueError, match="code_challenge"):
+        oauth.authorization_url(case["clientId"], case["redirectUri"], "\ud800")
+
+
+def test_a_pkce_pair_is_fresh_and_its_challenge_is_the_s256_one(
+    make_client: ClientFactory,
+) -> None:
+    pkce = CORPUS["deferred"]["pkce"]
+    oauth = make_client().oauth
+
+    first = oauth.create_pkce()
+
+    assert oauth.pkce_challenge(pkce["verifier"]) == pkce["challenge"]
+    assert re.fullmatch(pkce["generatedVerifierPattern"], first.verifier)
+    assert first.challenge == oauth.pkce_challenge(first.verifier)
+    assert first.method == pkce["method"]
+    assert oauth.create_pkce().verifier != first.verifier, "two pairs share a verifier"
+    assert first.verifier not in repr(first)
+
+
 def _every_operation(oauth: OauthAdapter) -> None:
     oauth.metadata()
     oauth.device_authorization("internetdata-cli", scope="account.read")
     oauth.exchange_device_code("internetdata-cli", "mo_dc_x")
     oauth.exchange_refresh_token("internetdata-cli", "mo_rt_x")
+    oauth.exchange_authorization_code(
+        "internetdata-cli", "mo_ac_x", "v" * 43, "http://127.0.0.1/cb"
+    )
     oauth.revoke("internetdata-cli", "mo_rt_x")
     oauth.poll_device_token("internetdata-cli", DEVICE)
 
@@ -348,6 +414,10 @@ def _call(oauth: OauthAdapter, operation: str, args: dict[str, str]) -> Any:
         return oauth.exchange_device_code(args["clientId"], args["deviceCode"])
     if operation == "exchangeRefreshToken":
         return oauth.exchange_refresh_token(args["clientId"], args["refreshToken"])
+    if operation == "exchangeAuthorizationCode":
+        return oauth.exchange_authorization_code(
+            args["clientId"], args["code"], args["codeVerifier"], args["redirectUri"]
+        )
     if operation == "revoke":
         return oauth.revoke(args["clientId"], args["token"])
     raise AssertionError(f"the corpus names an operation this suite does not know: {operation}")