diff --git a/.github/actions/build-package/action.yml b/.github/actions/build-package/action.yml new file mode 100644 index 000000000..24c38c132 --- /dev/null +++ b/.github/actions/build-package/action.yml @@ -0,0 +1,15 @@ +name: Build +description: Build and check the package into dist/. Shared by CI and Canary CI; expects the repository to be checked out. + +runs: + using: composite + steps: + - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0 + - name: Set up Python 3 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.10" + - name: Build and check package + shell: bash + run: | + just build diff --git a/.github/actions/static-checks/action.yml b/.github/actions/static-checks/action.yml new file mode 100644 index 000000000..485e7f0c7 --- /dev/null +++ b/.github/actions/static-checks/action.yml @@ -0,0 +1,29 @@ +name: Static Checks +description: Typecheck examples, lint, check formatting, and typecheck. Shared by CI and Canary CI; expects the repository to be checked out. + +runs: + using: composite + steps: + - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0 + - name: Set up Python 3 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.13" + - name: check examples w/ mypy (against python@3.13) + shell: bash + run: just typecheck-examples + # skip deps on all these since mypy installed everything + - name: check linting + shell: bash + run: just --no-deps lint + - name: check formatting + shell: bash + run: just --no-deps format-check + # pyright depends on node, which it handles and installs for itself as needed + # we _could_ run setup-node to make it available for it if we're having reliability problems + - name: check types + # only check against a modern version- unit tests will catch syntax errors on older versions + # this isn't user facing, this is just checking that our code is internally consistent + # e.g. a bug here wouldn't cause user CI to fail since the issue is internal to our codebase + shell: bash + run: just --no-deps typecheck diff --git a/.github/actions/test/action.yml b/.github/actions/test/action.yml new file mode 100644 index 000000000..b9e711811 --- /dev/null +++ b/.github/actions/test/action.yml @@ -0,0 +1,100 @@ +name: Test +description: Start stripe-mock, then run the tests. Shared by CI and Canary CI; expects the repository to be checked out. + +inputs: + python-version: + description: Python version to test against. + required: true + canary_channel: + description: >- + Canary channel (ga, beta, or private-preview) whose specs and fixtures + stripe-mock should serve. Empty uses the OPENAPI_VERSION release. + required: false + default: '' + +runs: + using: composite + steps: + - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0 + - name: Resolve stripe-mock OpenAPI inputs + id: openapi + shell: bash + env: + CANARY_CHANNEL: ${{ inputs.canary_channel }} + run: | + set -euo pipefail + + if [[ -z "$CANARY_CHANNEL" ]]; then + echo "version=$(< OPENAPI_VERSION)" >> "$GITHUB_OUTPUT" + exit 0 + fi + + case "$CANARY_CHANNEL" in + ga) + spec_name=spec3.sdk.json + fixtures_name=fixtures3.json + beta=false + ;; + beta) + spec_name=spec3.beta.sdk.json + fixtures_name=fixtures3.beta.json + beta=true + ;; + private-preview) + spec_name=spec3.private_preview.sdk.json + fixtures_name=fixtures3.private_preview.json + beta=true + ;; + *) + echo "::error::Unsupported canary channel: $CANARY_CHANNEL" + exit 1 + ;; + esac + + canary_dir="$GITHUB_WORKSPACE/.stripe-mock-canary" + mkdir -p "$canary_dir" + + spec_path="$canary_dir/$spec_name" + fixtures_path="$canary_dir/$fixtures_name" + canary_base="https://raw.githubusercontent.com/stripe/openapi/master/openapi/canary/$CANARY_CHANNEL" + curl_options=( + --retry 3 + --retry-all-errors + --fail + --silent + --show-error + ) + + curl "${curl_options[@]}" "$canary_base/$spec_name" -o "$spec_path" + curl "${curl_options[@]}" "$canary_base/$fixtures_name" -o "$fixtures_path" + + { + echo "spec_path=$spec_path" + echo "fixtures_path=$fixtures_path" + echo "beta=$beta" + } >> "$GITHUB_OUTPUT" + - name: Set up Python ${{ inputs.python-version }} + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: ${{ inputs.python-version }} + - uses: stripe/openapi/actions/stripe-mock@master + with: + openapi_version: ${{ steps.openapi.outputs.version }} + spec_path: ${{ steps.openapi.outputs.spec_path }} + fixtures: ${{ steps.openapi.outputs.fixtures_path }} + beta: ${{ steps.openapi.outputs.beta }} + + # Composite steps must name a shell; keep each OS on the shell CI used before. + - name: "run tests" + if: runner.os != 'Windows' + shell: bash + run: just test + env: + STRIPE_MOCK_HOST: localhost + - name: "run tests" + if: runner.os == 'Windows' + shell: pwsh + run: just test + env: + # Use IP instead of 'localhost' to avoid slow DNS resolution on Windows + STRIPE_MOCK_HOST: 127.0.0.1 diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml new file mode 100644 index 000000000..de4d00abb --- /dev/null +++ b/.github/workflows/canary.yml @@ -0,0 +1,89 @@ +name: Canary CI + +# Runs the same checks as CI against code generated from the canary specs. +# sdk-codegen force-pushes these branches; they are never released, so there is +# no publish job. +on: + workflow_dispatch: {} + push: + branches: + - canary-ga + - canary-beta + - canary-private-preview + +permissions: {} + +concurrency: + # Each push replaces the branch, so an older run's result is stale. + group: canary-ci-${{ github.ref_name }} + cancel-in-progress: true + +env: + # Map each canary branch to the channel stripe-mock serves. + CANARY_CHANNEL: >- + ${{ + github.ref_name == 'canary-ga' && 'ga' || + github.ref_name == 'canary-beta' && 'beta' || + github.ref_name == 'canary-private-preview' && 'private-preview' || + 'unsupported' + }} + +jobs: + lint: + name: Static Checks + runs-on: "ubuntu-24.04" + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: ./.github/actions/static-checks + + build: + name: Build + runs-on: "ubuntu-24.04" + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: ./.github/actions/build-package + + test: + name: Test (${{ matrix.python_version }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} + permissions: + contents: read + strategy: + fail-fast: false + matrix: + # Keep in sync with the test matrix in ci.yml. + os: + - "ubuntu-24.04" + python_version: + # The last ~5 versions, once we're on schedule + # https://docs.stripe.com/sdks/versioning?lang=python#stripe-sdk-language-version-support-policy + # https://endoflife.date/python + - "3.9" + - "3.10" + - "3.11" + - "3.12" + - "3.13" + - "3.14" + - "pypy-3.9" + - "pypy-3.10" + - "pypy-3.11" + include: + - os: windows-latest + # use any modern-ish version + python_version: "3.14" + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: ./.github/actions/test + with: + python-version: ${{ matrix.python_version }} + canary_channel: ${{ env.CANARY_CHANNEL }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f8a8332dc..ccc0711b4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,28 +28,10 @@ jobs: permissions: contents: read steps: - - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: Set up Python 3 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.13" - - name: check examples w/ mypy (against python@3.13) - run: just typecheck-examples - # skip deps on all these since mypy installed everything - - name: check linting - run: just --no-deps lint - - name: check formatting - run: just --no-deps format-check - # pyright depends on node, which it handles and installs for itself as needed - # we _could_ run setup-node to make it available for it if we're having reliability problems - - name: check types - # only check against a modern version- unit tests will catch syntax errors on older versions - # this isn't user facing, this is just checking that our code is internally consistent - # e.g. a bug here wouldn't cause user CI to fail since the issue is internal to our codebase - run: just --no-deps typecheck + - uses: ./.github/actions/static-checks build: name: Build @@ -57,19 +39,10 @@ jobs: permissions: contents: read steps: - - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - - name: Set up Python 3 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.10" - - - name: Build and check package - run: | - just build + - uses: ./.github/actions/build-package - name: "Upload Artifact" uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 @@ -85,6 +58,7 @@ jobs: strategy: fail-fast: false matrix: + # Keep in sync with the test matrix in canary.yml. os: - "ubuntu-24.04" python_version: @@ -105,27 +79,12 @@ jobs: # use any modern-ish version python_version: "3.14" steps: - - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: Read OpenAPI version - id: openapi - shell: bash - run: echo "version=$(< OPENAPI_VERSION)" >> "$GITHUB_OUTPUT" - - name: Set up Python ${{ matrix.python_version }} - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + - uses: ./.github/actions/test with: python-version: ${{ matrix.python_version }} - - uses: stripe/openapi/actions/stripe-mock@master - with: - openapi_version: ${{ steps.openapi.outputs.version }} - - - name: "run tests" - run: just test - env: - # Use IP instead of 'localhost' to avoid slow DNS resolution on Windows - STRIPE_MOCK_HOST: ${{ runner.os == 'Windows' && '127.0.0.1' || 'localhost' }} publish: name: Publish diff --git a/README.md b/README.md index f851cec19..c40ed3e96 100644 --- a/README.md +++ b/README.md @@ -471,12 +471,6 @@ just format # or: venv/bin/ruff format . --quiet ``` -Update bundled CA certificates from the [Mozilla cURL release][curl]: - -```sh -just update-certs -``` - [api-keys]: https://dashboard.stripe.com/account/apikeys [ruff]: https://github.com/astral-sh/ruff [connect]: https://stripe.com/connect diff --git a/justfile b/justfile index b156e797c..5e38fb99d 100644 --- a/justfile +++ b/justfile @@ -75,9 +75,6 @@ install group: venv # always log deps in CI, but don't do it locally python -I -m pip install -r deps/{{ group }}-requirements.txt --disable-pip-version-check {{ if env("CI", "") == "true" {""} else if is_dependency() == "true" {"--quiet"} else {""} }} -update-certs: - curl -o stripe/data/ca-certificates.crt https://curl.se/ca/cacert.pem - # create a virtualenv if it doesn't exist; always installs the local package [private] venv: diff --git a/stripe/_api_requestor.py b/stripe/_api_requestor.py index 2da869f0a..bdc725816 100644 --- a/stripe/_api_requestor.py +++ b/stripe/_api_requestor.py @@ -61,10 +61,12 @@ from stripe._base_address import BaseAddress from stripe._api_mode import ApiMode +from stripe._stripe_object import API_KEY_SERIALIZATION_CONSTANT if TYPE_CHECKING: from stripe._app_info import AppInfo from stripe._stripe_object import StripeObject + from stripe._stripe_context import StripeContext HttpVerb = Literal["get", "post", "delete"] @@ -165,6 +167,12 @@ def _new_requestor_with_options( """ Returns a new _APIRequestor instance with the same HTTP client but a (potentially) updated set of options. Useful for ensuring the original isn't modified, but any options the original had are still used. """ + if self.api_key == API_KEY_SERIALIZATION_CONSTANT: + raise error.AuthenticationError( + "This object was unpickled without API credentials. " + "Call reattach_api_key(api_key) on the object before making requests." + ) + options = options or {} new_options = self._options.to_dict() for key in PERSISTENT_OPTIONS_KEYS: @@ -174,6 +182,24 @@ def _new_requestor_with_options( options=RequestorOptions(**new_options), client=self._client ) + def with_stripe_context( + self, stripe_context: "Optional[Union[str, StripeContext]]" + ) -> "_APIRequestor": + """ + Returns a new _APIRequestor with the same configuration as this one, but + scoped to a different stripe_context. Unlike _new_requestor_with_options, + this always replaces stripe_context (even with None) and clears + stripe_account, since a context is self-contained and a stripe_account + inherited from whatever request produced this requestor should not leak + into requests scoped by it. + """ + new_options = self._options.to_dict() + new_options["stripe_context"] = stripe_context + new_options["stripe_account"] = None + return _APIRequestor( + options=RequestorOptions(**new_options), client=self._client + ) + @property def api_key(self): return self._options.api_key @@ -677,6 +703,12 @@ def _args_for_request_with_retries( """ Mechanism for issuing an API call. Used by request_raw and request_raw_async. """ + if self.api_key == API_KEY_SERIALIZATION_CONSTANT: + raise error.AuthenticationError( + "This object was unpickled without API credentials. " + "Call reattach_api_key(api_key) on the object before making requests." + ) + request_options = merge_options(self._options, options) # Special stripe_version handling for v2 requests: diff --git a/stripe/_http_client.py b/stripe/_http_client.py index 65c3ed684..51740e156 100644 --- a/stripe/_http_client.py +++ b/stripe/_http_client.py @@ -827,6 +827,23 @@ def close(self): pass +def _assert_no_header_injection(headers: Mapping[str, str]) -> None: + """Rejects CR, LF and NUL in a header name or value. + + pycurl's HTTPHEADER option takes raw "name: value" strings, assembled + here by string formatting rather than passed to a validating library + call. A CR or LF in either half would let the remainder be parsed as an + additional header line. + """ + for key, value in headers.items(): + for part in (key, value): + if "\r" in part or "\n" in part or "\0" in part: + raise ValueError( + "Header names and values may not contain CR, LF or " + "NUL characters." + ) + + class PycurlClient(HTTPClient): class _ParsedProxy(TypedDict, total=False): http: Optional["ParseResult"] @@ -854,8 +871,6 @@ def __init__( _lib = pycurl self.pycurl = _lib - # Initialize this within the object so that we can reuse connections. - self._curl = _lib.Curl() self._parsed_proxy = {} # need to urlparse the proxy, since PyCurl @@ -869,6 +884,20 @@ def __init__( # but we know value to be a string because all the value types on Proxy_ are strings. self._parsed_proxy[scheme] = urlparse(cast(str, value)) + def _get_curl(self): + """ + Returns this thread's Curl handle, creating it on first use. + + A libcurl easy handle must never be used by more than one thread at a + time, so each thread gets its own. Reusing a handle within a thread + lets us keep its established connections. + """ + curl = getattr(self._thread_local, "curl", None) + if curl is None: + curl = self.pycurl.Curl() + self._thread_local.curl = curl + return curl + def parse_headers(self, data): if "\r\n" not in data: return {} @@ -927,47 +956,49 @@ def _request_internal( # pristine state, but notably reset() doesn't reset connections, so we # still get to take advantage of those by virtue of re-using the same # object. - self._curl.reset() + curl = self._get_curl() + curl.reset() proxy = self._get_proxy(url) if proxy: if proxy.hostname: - self._curl.setopt(self.pycurl.PROXY, proxy.hostname) + curl.setopt(self.pycurl.PROXY, proxy.hostname) if proxy.port: - self._curl.setopt(self.pycurl.PROXYPORT, proxy.port) + curl.setopt(self.pycurl.PROXYPORT, proxy.port) if proxy.username or proxy.password: - self._curl.setopt( + curl.setopt( self.pycurl.PROXYUSERPWD, "%s:%s" % (proxy.username, proxy.password), ) if method == "get": - self._curl.setopt(self.pycurl.HTTPGET, 1) + curl.setopt(self.pycurl.HTTPGET, 1) elif method == "post": - self._curl.setopt(self.pycurl.POST, 1) - self._curl.setopt(self.pycurl.POSTFIELDS, post_data) + curl.setopt(self.pycurl.POST, 1) + curl.setopt(self.pycurl.POSTFIELDS, post_data) else: - self._curl.setopt(self.pycurl.CUSTOMREQUEST, method.upper()) + curl.setopt(self.pycurl.CUSTOMREQUEST, method.upper()) # pycurl doesn't like unicode URLs - self._curl.setopt(self.pycurl.URL, url) - - self._curl.setopt(self.pycurl.WRITEFUNCTION, b.write) - self._curl.setopt(self.pycurl.HEADERFUNCTION, rheaders.write) - self._curl.setopt(self.pycurl.NOSIGNAL, 1) - self._curl.setopt(self.pycurl.CONNECTTIMEOUT, 30) - self._curl.setopt(self.pycurl.TIMEOUT, 80) - self._curl.setopt( + curl.setopt(self.pycurl.URL, url) + + curl.setopt(self.pycurl.WRITEFUNCTION, b.write) + curl.setopt(self.pycurl.HEADERFUNCTION, rheaders.write) + curl.setopt(self.pycurl.NOSIGNAL, 1) + curl.setopt(self.pycurl.CONNECTTIMEOUT, 30) + curl.setopt(self.pycurl.TIMEOUT, 80) + _assert_no_header_injection(headers) + curl.setopt( self.pycurl.HTTPHEADER, ["%s: %s" % (k, v) for k, v in dict(headers).items()], ) if self._verify_ssl_certs: - self._curl.setopt(self.pycurl.CAINFO, stripe.ca_bundle_path) + curl.setopt(self.pycurl.CAINFO, stripe.ca_bundle_path) else: - self._curl.setopt(self.pycurl.SSL_VERIFYHOST, False) + curl.setopt(self.pycurl.SSL_VERIFYHOST, False) try: - self._curl.perform() + curl.perform() except self.pycurl.error as e: self._handle_request_error(e) @@ -977,7 +1008,7 @@ def _request_internal( else: rcontent = b.getvalue().decode("utf-8") - rcode = self._curl.getinfo(self.pycurl.RESPONSE_CODE) + rcode = curl.getinfo(self.pycurl.RESPONSE_CODE) headers = self.parse_headers(rheaders.getvalue().decode("utf-8")) return rcontent, rcode, headers @@ -1026,7 +1057,10 @@ def _get_proxy(self, url) -> Optional["ParseResult"]: return None def close(self): - pass + curl = getattr(self._thread_local, "curl", None) + if curl is not None: + curl.close() + self._thread_local.curl = None class UrllibClient(HTTPClient): diff --git a/stripe/_stripe_object.py b/stripe/_stripe_object.py index 8fe6d87d7..56ac30eb8 100644 --- a/stripe/_stripe_object.py +++ b/stripe/_stripe_object.py @@ -49,6 +49,9 @@ from stripe._api_requestor import _APIRequestor # pyright: ignore[reportPrivateUsage] +API_KEY_SERIALIZATION_CONSTANT = "API_KEY_SERIALIZATION_CONSTANT" + + @overload def _compute_diff( current: Dict[str, Any], previous: Optional[Dict[str, Any]] @@ -156,6 +159,50 @@ def stripe_account(self): def stripe_version(self): return self._requestor.stripe_version + def reattach_api_key(self, api_key: str) -> None: + """Attach credentials to an unpickled object and its nested objects. + + Each object retains its saved API version and connected account. + Objects that already have credentials cannot be reattached. + """ + if self.api_key != API_KEY_SERIALIZATION_CONSTANT: + raise ValueError( + "API credentials can only be reattached to an unpickled " + "object that has not already been reattached." + ) + if ( + not isinstance(cast(object, api_key), str) + or not api_key.strip() + or api_key == API_KEY_SERIALIZATION_CONSTANT + ): + raise ValueError("api_key must be a non-empty, valid API key.") + + from stripe._api_requestor import _APIRequestor # pyright: ignore[reportPrivateUsage] + + seen: Set[int] = set() + + def reattach(value: Any) -> None: + if id(value) in seen: + return + seen.add(id(value)) + if isinstance(value, StripeObject): + if value.api_key == API_KEY_SERIALIZATION_CONSTANT: + value._requestor = _APIRequestor._global_with_options( # pyright: ignore[reportPrivateUsage] + api_key=api_key, + stripe_version=value.stripe_version, + stripe_account=value.stripe_account, + ) + for nested in value._data.values(): + reattach(nested) + elif isinstance(value, dict): + for nested in cast(Dict[Any, Any], value).values(): + reattach(nested) + elif isinstance(value, (list, tuple)): + for nested in cast(Union[List[Any], Tuple[Any, ...]], value): + reattach(nested) + + reattach(self) + @property def last_response(self) -> Optional[StripeResponse]: return self._last_response @@ -298,7 +345,7 @@ def __reduce__(self) -> Tuple[Any, ...]: type(self), # callable ( # args getattr(self, "id", None), - self.api_key, + API_KEY_SERIALIZATION_CONSTANT, self.stripe_version, self.stripe_account, ), diff --git a/stripe/_util.py b/stripe/_util.py index e034b209f..995967aa5 100644 --- a/stripe/_util.py +++ b/stripe/_util.py @@ -243,6 +243,7 @@ def _convert_to_stripe_object( elif isinstance(resp, dict): resp = resp.copy() klass_name = resp.get("object") + requestor_uses_response_context = False if isinstance(klass_name, str): if is_v2_deleted_object: # circular import @@ -254,6 +255,7 @@ def _convert_to_stripe_object( event_type = resp.get("type", "") klass = get_v2_event_class(event_type) + requestor_uses_response_context = True else: from stripe._object_classes import get_object_class @@ -279,6 +281,17 @@ def _convert_to_stripe_object( api_mode=api_mode, ) + if requestor_uses_response_context: + # A directly-retrieved object carries the requestor of whatever + # account fetched it (e.g. a platform account), but its `context` + # field is the self-contained auth context for its own account. + # Rescope the requestor the same way EventNotification.__init__ + # scopes its client so fetch_related_object() uses the correct + # headers. + obj._requestor = obj._requestor.with_stripe_context( + getattr(obj, "context", None) + ) + # We only need to update _retrieve_params when special params were # actually passed. Otherwise, leave it as is as the list / search result # constructors will instantiate their own params. diff --git a/stripe/_webhook.py b/stripe/_webhook.py index a9a041454..9c39d59a7 100644 --- a/stripe/_webhook.py +++ b/stripe/_webhook.py @@ -2,8 +2,10 @@ import json import time from collections import OrderedDict +from dataclasses import dataclass from hashlib import sha256 from typing import Any, Dict, Optional, Union +from urllib.parse import quote # Used for global variables import stripe # noqa: IMP101 @@ -19,6 +21,13 @@ """ +@dataclass +class _DebugMetadata: + secret: Optional[str] = None + destination: Optional[str] = None + payload: Optional[str] = None + + def build_v1_event(values: Dict[str, Any], requestor: _APIRequestor) -> Event: """ Internal helper for centralizing v1 event creation @@ -180,8 +189,7 @@ def verify_header( expected_sig = cls._compute_signature(signed_payload, secret) if not any(secure_compare(expected_sig, s) for s in signatures): raise SignatureVerificationError( - "No signatures found matching the expected signature for " - "payload", + cls._signature_error_message(header, str(payload), secret), header, payload, ) @@ -194,3 +202,91 @@ def verify_header( ) return True + + @classmethod + def _signature_error_message( + cls, header: str, payload: str, secret: str + ) -> str: + """Build an HMAC-mismatch message using optional header metadata.""" + metadata = cls._signature_debug_metadata(header) + + # If metadata has an asterisk-masked secret, compare against its length and last four characters + masked_secret = metadata.secret or "" + secret_suffix = secret[-4:] + if "*" in masked_secret and ( + len(secret) != len(masked_secret) + or secret_suffix != masked_secret[-4:] + ): + dashboard_url = "https://dashboard.stripe.com/webhooks" + if metadata.destination is not None: + dashboard_url += "/" + quote(metadata.destination, safe="") + return ( + "Webhook signature verification failed. This request may not " + "have originated from Stripe.\n\n" + f"The signing secret you provided is {len(secret)} characters " + f"long and ends in `{secret_suffix}`. However, the signing " + "secret for this destination is " + f"{len(masked_secret)} characters long and looks like " + f"`{masked_secret}`. Ensure you're using the signing secret " + "for this destination, as shown on the Dashboard: " + f"{dashboard_url}\n\n" + "Learn more: https://docs.stripe.com/webhooks/signature" + ) + + # If metadata includes the truncated payload hash, compare with the payload passed in + expected_hash = (metadata.payload or "").lower() + if len(expected_hash) == 8 and all( + character in "0123456789abcdef" for character in expected_hash + ): + actual_hash = sha256(payload.encode("utf-8")).hexdigest()[-8:] + if expected_hash != actual_hash: + return ( + "Webhook signature verification failed.\n\n" + "The request body you passed to this function differs " + "from the request body sent by Stripe to this webhook " + "destination.\n" + "The SHA-256 hash of the body should end in " + f"`{expected_hash}`. However, the SHA-256 hash of the body " + f"you provided ends in `{actual_hash}`.\n\n" + "Make sure your code does not reformat or otherwise alter " + "the raw HTTP request body before passing it to this " + "function.\n\n" + "Learn more: https://docs.stripe.com/webhooks/signature" + ) + + # Fall back to the generic message if no debug metadata available + return ( + "No signatures found matching the expected signature for payload" + ) + + @classmethod + def _signature_debug_metadata(cls, header: str) -> _DebugMetadata: + """Extract metadata from the stripe-signature header value to help debug verification failures.""" + # For each metadata key, extract the first value found in the header + metadata: Dict[str, Optional[str]] = {} + for item in header.split(","): + key, separator, value = item.lstrip().partition("=") + if ( + key in ("secret", "destination", "payload") + and key not in metadata + ): + metadata[key] = ( + cls._safe_metadata_value(value) if separator else None + ) + return _DebugMetadata( + metadata.get("secret"), + metadata.get("destination"), + metadata.get("payload"), + ) + + @staticmethod + def _safe_metadata_value(value: str) -> Optional[str]: + """Return a bounded UTF-8 metadata value, or None if unusable.""" + # Ignore overly long, potentially attacker-provided metadata values + if len(value) > 100: + return None + try: + value.encode("utf-8") + except UnicodeEncodeError: + return None + return value.strip() or None diff --git a/tests/api_resources/test_list_object.py b/tests/api_resources/test_list_object.py index 02568c4b7..895094d36 100644 --- a/tests/api_resources/test_list_object.py +++ b/tests/api_resources/test_list_object.py @@ -1,4 +1,5 @@ import json +import pickle import pytest @@ -297,6 +298,68 @@ def test_iter_two_pages(self, http_client_mock): assert seen == ["pm_123", "pm_124", "pm_125", "pm_126"] + @pytest.fixture + def restored_list(self, monkeypatch): + lo = stripe.ListObject.construct_from( + self.pageable_model_response(["pm_123"], True), + "producer-key-sentinel", + stripe_account="example-account", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(lo)) + restored.reattach_api_key("worker-key-sentinel") + return restored + + def test_iter_uses_reattached_api_key_on_every_page( + self, http_client_mock, restored_list + ): + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_123", + rbody=json.dumps(self.pageable_model_response(["pm_124"], True)), + ) + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_124", + rbody=json.dumps(self.pageable_model_response(["pm_125"], False)), + ) + + seen = [item["id"] for item in restored_list.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124", "pm_125"] + for starting_after in ("pm_123", "pm_124"): + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string=f"starting_after={starting_after}", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + + def test_iter_reverse_uses_reattached_api_key( + self, http_client_mock, restored_list + ): + restored_list._retrieve_params = {"ending_before": "pm_124"} + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="ending_before=pm_123", + rbody=json.dumps(self.pageable_model_response(["pm_122"], False)), + ) + + seen = [item["id"] for item in restored_list.auto_paging_iter()] + + assert seen == ["pm_123", "pm_122"] + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string="ending_before=pm_123", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + def test_iter_reverse(self, http_client_mock): lo = stripe.ListObject.construct_from( self.pageable_model_response(["pm_125", "pm_126"], True), "mykey" @@ -655,6 +718,34 @@ async def test_iter_one_page(self, http_client_mock): assert seen == ["pm_123", "pm_124"] + @pytest.mark.anyio + async def test_iter_uses_reattached_api_key( + self, http_client_mock, monkeypatch + ): + lo = stripe.ListObject.construct_from( + self.pageable_model_response(["pm_123"], True), + "producer-key-sentinel", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(lo)) + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_123", + rbody=json.dumps(self.pageable_model_response(["pm_124"], False)), + ) + + seen = [item["id"] async for item in restored.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124"] + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_123", + api_key="worker-key-sentinel", + ) + @pytest.mark.anyio async def test_iter_two_pages(self, http_client_mock): lo = stripe.ListObject.construct_from( diff --git a/tests/api_resources/test_list_object_v2.py b/tests/api_resources/test_list_object_v2.py index 84759e873..a7581b142 100644 --- a/tests/api_resources/test_list_object_v2.py +++ b/tests/api_resources/test_list_object_v2.py @@ -1,6 +1,7 @@ from __future__ import absolute_import, division, print_function import json +import pickle import pytest @@ -147,6 +148,33 @@ def test_iter_forwards_api_key(self, http_client_mock: HTTPClientMock): api_key="sk_test_iter_forwards_options", ) + def test_iter_uses_reattached_api_key(self, http_client_mock, monkeypatch): + lo = ListObject.construct_from( + self.pageable_model_response( + ["pm_123"], "/v2/pageablemodels?page=page_2" + ), + "producer-key-sentinel", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(lo)) + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v2/pageablemodels", + query_string="page=page_2", + rbody=json.dumps(self.pageable_model_response(["pm_124"], None)), + ) + + seen = [item["id"] for item in restored.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124"] + http_client_mock.assert_requested( + "get", + path="/v2/pageablemodels", + query_string="page=page_2", + api_key="worker-key-sentinel", + ) + class TestAutoPagingAsync: @staticmethod diff --git a/tests/api_resources/test_search_result_object.py b/tests/api_resources/test_search_result_object.py index 9db977921..5d640e374 100644 --- a/tests/api_resources/test_search_result_object.py +++ b/tests/api_resources/test_search_result_object.py @@ -1,4 +1,5 @@ import json +import pickle import pytest @@ -256,6 +257,35 @@ def test_iter_two_pages(self, http_client_mock): assert seen == ["pm_123", "pm_124", "pm_125", "pm_126"] + def test_iter_uses_reattached_api_key(self, http_client_mock, monkeypatch): + sro = stripe.SearchResultObject.construct_from( + self.pageable_model_response(["pm_123"], True, "token"), + "producer-key-sentinel", + stripe_account="example-account", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(sro)) + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="page=token", + rbody=json.dumps( + self.pageable_model_response(["pm_124"], False, None) + ), + ) + + seen = [item["id"] for item in restored.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124"] + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string="page=token", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + class TestAutoPagingAsync: @staticmethod diff --git a/tests/test_api_requestor.py b/tests/test_api_requestor.py index dadb1232e..2b94d7c98 100644 --- a/tests/test_api_requestor.py +++ b/tests/test_api_requestor.py @@ -669,6 +669,37 @@ def test_uses_instance_context(self, http_client_mock): stripe_context=context, ) + def test_with_stripe_context_clears_stripe_account( + self, requestor, http_client_mock: HTTPClientMock + ): + """ + with_stripe_context is used to scope a requestor to a v2 Event's own + context (see Event's construction in _util._convert_to_stripe_object). + Unlike _new_requestor_with_options, it must always clear stripe_account, + even though one was already set, so a stale account from whatever + request produced the original requestor can't leak into requests made + with the new one. + """ + requestor = requestor._new_requestor_with_options( + RequestOptions(stripe_account="acct_original") + ) + + requestor = requestor.with_stripe_context("acct_context") + + http_client_mock.stub_request( + "get", path=self.v1_path, rbody="{}", rcode=200 + ) + + requestor.request("get", self.v1_path, {}, base_address="api") + + http_client_mock.assert_requested( + "get", + stripe_context="acct_context", + ) + call = http_client_mock.get_last_call() + assert call.headers is not None + assert "Stripe-Account" not in call.headers + def test_sets_default_http_client(self, mocker): assert not stripe.default_http_client diff --git a/tests/test_http_client.py b/tests/test_http_client.py index 8b3ab71fb..937eec3fa 100644 --- a/tests/test_http_client.py +++ b/tests/test_http_client.py @@ -2,6 +2,7 @@ import base64 import json import sys +import threading from typing import Any, Callable, Dict, List, Optional from unittest.mock import MagicMock, Mock, call, patch @@ -1149,6 +1150,136 @@ def _check_call( return _check_call + def test_request_rejects_header_injection( + self, mocked_request_lib, make_request: MakeReqFunc, mock_response + ): + mock_response(mocked_request_lib, '{"foo": "baz"}', 200) + + hostile_headers = [ + {"Stripe-Context": "acct_123\r\nX-Injected: 1"}, + {"Stripe-Request-Trigger": "event=evt_1\nX-Injected: 1"}, + {"Authorization": "Bearer sk_test_123\r\n"}, + {"Authorization": "Bearer sk_test_123\0"}, + {"X-Injected\r\nEvil": "value"}, + ] + + for headers in hostile_headers: + with pytest.raises(ValueError): + make_request("get", self.valid_url, headers, None) + + @pytest.fixture + def created_curls(self, mocked_request_lib): + curls: List[Mock] = [] + + def make_curl(): + curl = Mock() + curl.getinfo.return_value = 200 + curls.append(curl) + return curl + + mocked_request_lib.Curl = Mock(side_effect=make_curl) + return curls + + @staticmethod + def setopt_values(curl, option): + return [ + c.args[1] + for c in curl.setopt.call_args_list + if c.args[0] == option + ] + + def test_uses_one_curl_handle_per_thread( + self, mocked_request_lib, created_curls + ): + client = self.REQUEST_CLIENT(proxy=self.PROXY, _lib=mocked_request_lib) + + client.request("get", self.valid_url, {}) + client.request("get", self.valid_url, {}) + assert len(created_curls) == 1 + + errors: List[BaseException] = [] + + def request_in_thread(): + try: + client.request("get", self.valid_url, {}) + except BaseException as e: + errors.append(e) + + thread = threading.Thread(target=request_in_thread) + thread.start() + thread.join(timeout=5) + + assert errors == [] + assert len(created_curls) == 2 + assert created_curls[0] is not created_curls[1] + + def test_concurrent_requests_do_not_share_curl_state( + self, mocked_request_lib + ): + client = self.REQUEST_CLIENT(proxy=self.PROXY, _lib=mocked_request_lib) + url_a = "https://api.stripe.com/v1/payouts" + url_b = "https://api.stripe.com/v1/transfers" + a_performing = threading.Event() + release_a = threading.Event() + errors: List[BaseException] = [] + + # Hold request A inside perform() until request B has fully run. If the + # threads shared a handle, B's settings would replace A's mid-request. + def block_first_perform(): + if not a_performing.is_set(): + a_performing.set() + assert release_a.wait(timeout=5) + + def request_a(): + try: + client.request( + "post", url_a, {"Authorization": "Bearer sk_test_A"}, "a=1" + ) + except BaseException as e: + errors.append(e) + + curl_a = Mock() + curl_a.getinfo.return_value = 200 + curl_a.perform.side_effect = block_first_perform + curl_b = Mock() + curl_b.getinfo.return_value = 200 + mocked_request_lib.Curl = Mock(side_effect=[curl_a, curl_b]) + + thread_a = threading.Thread(target=request_a) + thread_a.start() + assert a_performing.wait(timeout=5) + + client.request( + "post", url_b, {"Authorization": "Bearer sk_test_B"}, "b=2" + ) + release_a.set() + thread_a.join(timeout=5) + + assert errors == [] + lib = mocked_request_lib + assert self.setopt_values(curl_a, lib.URL) == [url_a] + assert self.setopt_values(curl_a, lib.POSTFIELDS) == ["a=1"] + assert self.setopt_values(curl_a, lib.HTTPHEADER) == [ + ["Authorization: Bearer sk_test_A"] + ] + assert self.setopt_values(curl_b, lib.URL) == [url_b] + assert self.setopt_values(curl_b, lib.POSTFIELDS) == ["b=2"] + assert self.setopt_values(curl_b, lib.HTTPHEADER) == [ + ["Authorization: Bearer sk_test_B"] + ] + + def test_close_closes_this_threads_curl_handle( + self, mocked_request_lib, created_curls + ): + client = self.REQUEST_CLIENT(proxy=self.PROXY, _lib=mocked_request_lib) + client.request("get", self.valid_url, {}) + + client.close() + + created_curls[0].close.assert_called_once_with() + client.request("get", self.valid_url, {}) + assert len(created_curls) == 2 + class TestPycurlClientHttpProxy(TestPycurlClient): PROXY = "http://user:withPwd@slap:8888/" diff --git a/tests/test_stripe_object.py b/tests/test_stripe_object.py index aecd64938..6873b915a 100644 --- a/tests/test_stripe_object.py +++ b/tests/test_stripe_object.py @@ -8,7 +8,7 @@ import stripe from stripe._invoice import Invoice -from stripe._stripe_object import StripeObject +from stripe._stripe_object import API_KEY_SERIALIZATION_CONSTANT, StripeObject # We use this because it has a map, "restriction.currency_options" from string -> CurrencyOptions nested class. SAMPLE_PROMOTION_CODE = json.loads( @@ -274,30 +274,365 @@ def test_repr(self): assert '"date": 1511136000' in res assert '"dec": "1.23"' in res - def test_pickling(self): - obj = StripeObject("foo", "bar", myparam=5) - - obj["object"] = "boo" - obj.refresh_from( + @pytest.mark.parametrize("protocol", range(pickle.HIGHEST_PROTOCOL + 1)) + @pytest.mark.parametrize( + "destination_key", [None, "destination-key-sentinel"] + ) + def test_pickling(self, protocol, destination_key, monkeypatch): + obj = stripe.Customer.construct_from( { - "fala": "lalala", - # ensures that empty strings are correctly unpickled in Py3 - "emptystring": "", + "id": "resource", + "object": "customer", + "description": "example", + "metadata": {"emptystring": ""}, }, - api_key="bar", - partial=True, + "producer-key-sentinel", + stripe_version="2017-08-15", + stripe_account="example-account", + ) + obj.metadata.api_key = "nested-key-sentinel" + nested = stripe.Customer.construct_from( + {"id": "nested-resource", "object": "customer"}, + "nested-key-sentinel", + stripe_version="2018-02-28", + stripe_account="nested-example-account", + ) + obj.containers = [{"nested": nested}] + original_requestor = obj._requestor + payload = obj.to_dict() + + for value in (obj.metadata, obj): + assert value.__reduce__()[1][1] == API_KEY_SERIALIZATION_CONSTANT + pickled = pickle.dumps(value, protocol=protocol) + assert b"producer-key-sentinel" not in pickled + assert b"nested-key-sentinel" not in pickled + + monkeypatch.setattr(stripe, "api_key", destination_key) + restored = pickle.loads(pickled) + + assert type(restored) is stripe.Customer + assert restored.to_dict() == payload + for value in (restored, restored.metadata): + assert value.api_key == API_KEY_SERIALIZATION_CONSTANT + assert value.stripe_version == "2017-08-15" + assert value.stripe_account == "example-account" + assert obj.api_key == "producer-key-sentinel" + assert obj.metadata.api_key == "nested-key-sentinel" + assert obj._requestor is original_requestor + assert obj.to_dict() == payload + + restored_nested = restored.containers[0]["nested"] + assert restored_nested.api_key == API_KEY_SERIALIZATION_CONSTANT + assert restored_nested.stripe_account == "nested-example-account" + assert restored_nested.stripe_version == "2018-02-28" + + restored.reattach_api_key("reattached-key-sentinel") + for value in (restored, restored.metadata, restored_nested): + assert value.api_key == "reattached-key-sentinel" + assert restored_nested.stripe_account == "nested-example-account" + assert restored_nested.stripe_version == "2018-02-28" + assert stripe.api_key == destination_key + + pickled = pickle.dumps(restored, protocol=protocol) + for key in ( + b"producer-key-sentinel", + b"nested-key-sentinel", + b"destination-key-sentinel", + b"reattached-key-sentinel", + ): + assert key not in pickled + + def test_pickling_verified_webhook(self, monkeypatch): + payload = json.dumps( + { + "object": "event", + "data": { + "object": {"object": "customer", "metadata": {"empty": ""}} + }, + } ) + monkeypatch.setattr(stripe, "api_key", "producer-key-sentinel") + signature = stripe.WebhookSignature.generate_signature_header( + payload, "webhook-test-secret" + ) + event = stripe.Webhook.construct_event( + payload, signature, "webhook-test-secret" + ) + pickled = pickle.dumps(event) + assert b"producer-key-sentinel" not in pickled + monkeypatch.setattr(stripe, "api_key", "destination-key-sentinel") + restored = pickle.loads(pickled) + + assert type(restored) is stripe.Event + assert type(restored.data.object) is stripe.Customer + assert restored.to_dict() == event.to_dict() + for value in ( + restored, + restored.data, + restored.data.object, + restored.data.object.metadata, + ): + assert value.api_key == API_KEY_SERIALIZATION_CONSTANT + assert event.api_key == "producer-key-sentinel" - assert obj.fala == "lalala" + @pytest.fixture + def restored_customer(self, monkeypatch): + obj = stripe.Customer.construct_from( + {"id": "resource", "object": "customer"}, + "producer-key-sentinel", + stripe_account="example-account", + ) + monkeypatch.setattr(stripe, "api_key", None) + return pickle.loads(pickle.dumps(obj)) + + @pytest.mark.parametrize("global_key", [None, "global-key-sentinel"]) + @pytest.mark.parametrize("per_call_key", [None, "per-call-key-sentinel"]) + def test_restored_delete_requires_reattachment( + self, + http_client_mock, + restored_customer, + monkeypatch, + global_key, + per_call_key, + ): + monkeypatch.setattr(stripe, "api_key", global_key) + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored_customer.delete(api_key=per_call_key) + http_client_mock.assert_no_request() + + def test_reattach_api_key(self, http_client_mock, restored_customer): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer"}', + ) + restored_customer.refresh() + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + assert ( + pickle.loads(pickle.dumps(restored_customer)).api_key + == API_KEY_SERIALIZATION_CONSTANT + ) - pickled = pickle.dumps(obj) - newobj = pickle.loads(pickled) + @pytest.mark.parametrize( + "key", [None, "", " ", 123, API_KEY_SERIALIZATION_CONSTANT] + ) + def test_reattach_api_key_rejects_invalid_keys( + self, restored_customer, key + ): + with pytest.raises(ValueError, match="api_key"): + restored_customer.reattach_api_key(key) + assert restored_customer.api_key == API_KEY_SERIALIZATION_CONSTANT + + def test_reattach_api_key_rejects_attached_objects( + self, restored_customer + ): + with pytest.raises(ValueError, match="only be reattached"): + stripe.Customer("cus_123").reattach_api_key("key") + restored_customer.reattach_api_key("key") + with pytest.raises(ValueError, match="only be reattached"): + restored_customer.reattach_api_key("other-key") + assert restored_customer.api_key == "key" + + def test_reattach_api_key_handles_cycles_and_attached_children( + self, restored_customer + ): + attached = StripeObject(api_key="child-key") + restored_customer._data["nested"] = [ + restored_customer, + {"attached": attached}, + ] + restored_customer.reattach_api_key("key") + assert restored_customer.api_key == "key" + assert attached.api_key == "child-key" + + @pytest.mark.parametrize("copy_method", [copy, deepcopy]) + def test_copy_detached_object( + self, restored_customer, monkeypatch, copy_method + ): + monkeypatch.setattr(stripe, "api_key", "global-key") + copied = copy_method(restored_customer) + assert copied.api_key == API_KEY_SERIALIZATION_CONSTANT + assert copied.stripe_account == "example-account" + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + copied._request( + "get", "/v1/customers/resource", base_address="api" + ) + + @pytest.mark.parametrize("method", ["_request", "_request_stream"]) + @pytest.mark.parametrize("per_call_key", [None, "per-call-key-sentinel"]) + def test_detached_request_guard( + self, restored_customer, method, http_client_mock, per_call_key + ): + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + getattr(restored_customer, method)( + "get", + "/v1/customers/resource", + params={"api_key": per_call_key}, + ) + http_client_mock.assert_no_request() - assert newobj.id == "foo" - assert newobj.api_key == "bar" - assert newobj["object"] == "boo" - assert newobj.fala == "lalala" - assert newobj.emptystring == "" + @pytest.mark.anyio + @pytest.mark.parametrize( + "method", ["_request_async", "_request_stream_async"] + ) + @pytest.mark.parametrize("per_call_key", [None, "per-call-key-sentinel"]) + async def test_detached_async_request_guard( + self, restored_customer, method, http_client_mock, per_call_key + ): + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + await getattr(restored_customer, method)( + "get", + "/v1/customers/resource", + params={"api_key": per_call_key}, + ) + http_client_mock.assert_no_request() + + def test_detached_option_setters_require_reattachment( + self, restored_customer + ): + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored_customer.api_key = "key" + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored_customer.refresh_from({}, api_key="key") + + def test_restored_refresh_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "description": "refreshed"}', + ) + + assert restored_customer.refresh() is restored_customer + + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + assert restored_customer.description == "refreshed" + assert stripe.api_key is None + assert b"worker-key-sentinel" not in pickle.dumps(restored_customer) + + @pytest.mark.anyio + async def test_restored_refresh_async_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer"}', + ) + + await restored_customer.refresh_async() + + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + + def test_refresh_preserves_retrieve_params(self, http_client_mock): + obj = stripe.Customer( + "resource", "producer-key-sentinel", expand=["sources"] + ) + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + query_string="expand[0]=sources", + rbody='{"id": "resource", "object": "customer"}', + ) + + obj.refresh() + + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + query_string="expand[0]=sources", + api_key="producer-key-sentinel", + ) + + def test_restored_save_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + restored_customer.description = "changed" + http_client_mock.stub_request( + "post", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "description": "changed"}', + ) + + restored_customer.save() + + http_client_mock.assert_requested( + "post", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + + def test_save_keeps_positional_idempotency_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + restored_customer.description = "changed" + http_client_mock.stub_request( + "post", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "description": "changed"}', + ) + + restored_customer.save("idempotency-sentinel") + + http_client_mock.assert_requested( + "post", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + idempotency_key="idempotency-sentinel", + ) + + def test_restored_delete_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "delete", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "deleted": true}', + ) + + restored_customer.delete(api_key="worker-key-sentinel") + + http_client_mock.assert_requested( + "delete", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) def test_deletion(self): obj = StripeObject("id", "key") diff --git a/tests/test_v2_event.py b/tests/test_v2_event.py index 4fc0dc682..797ac01cf 100644 --- a/tests/test_v2_event.py +++ b/tests/test_v2_event.py @@ -1,6 +1,8 @@ # -*- coding: utf-8 -*- # File copied from our code generator; changes here will be overwritten. import json +import pickle +import stripe from typing import Any, Callable, Dict, Optional, Union from typing_extensions import assert_type @@ -17,6 +19,7 @@ V1BillingMeterErrorReportTriggeredEvent, ) from stripe.events._v1_product_updated_event import ( + V1ProductUpdatedEvent, V1ProductUpdatedEventNotification, ) from stripe.v2.core._event import ( @@ -40,6 +43,32 @@ class TestV2Event(object): + def test_pickled_event_requires_reattachment( + self, http_client_mock, v2_payload_no_data + ): + event = V1BillingMeterErrorReportTriggeredEvent.construct_from( + json.loads(v2_payload_no_data), "producer-key-sentinel" + ) + restored = pickle.loads(pickle.dumps(event)) + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored.fetch_related_object() + http_client_mock.assert_no_request() + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/billing/meters/mtr_123", + rbody='{"id": "mtr_123", "object": "billing.meter"}', + ) + restored.fetch_related_object() + http_client_mock.assert_requested( + "get", + path="/v1/billing/meters/mtr_123", + api_key="worker-key-sentinel", + stripe_context="acct_123", + ) + @pytest.fixture(scope="function") def v2_payload_no_data(self): return json.dumps( @@ -517,3 +546,62 @@ async def test_related_object_retains_event_context_async( http_client_mock.assert_requested( "delete", path=path, stripe_context="acct_child" ) + + def test_direct_retrieve_related_object_retains_event_context( + self, http_client_mock: HTTPClientMock + ): + """ + Unlike EventNotification (built from a webhook), a directly-retrieved + Event doesn't go through StripeClient.with_stripe_context in its own + construction, so historically it kept whatever stripe_account retrieved + it. Make sure fetch_related_object() only ever uses the event's own + context, with no stale account from the retrieving client leaking in. + """ + event_path = "/v2/core/events/evt_123" + related_path = "/v1/products/prod_shared" + + http_client_mock.stub_request( + "get", + path=event_path, + rbody=json.dumps( + { + "id": "evt_123", + "object": "v2.core.event", + "type": "v1.product.updated", + "created": "2022-02-15T00:27:45.330Z", + "livemode": False, + "context": "acct_child", + "related_object": { + "id": "prod_shared", + "type": "product", + "url": related_path, + }, + } + ), + ) + http_client_mock.stub_request( + "get", + path=related_path, + rbody=json.dumps({"id": "prod_shared", "object": "product"}), + ) + + client = StripeClient( + api_key="sk_test_1234", + stripe_account="acct_platform", + http_client=http_client_mock.get_mock_http_client(), + ) + + event = client.v2.core.events.retrieve("evt_123") + assert isinstance(event, V1ProductUpdatedEvent) + + product = event.fetch_related_object() + assert product.id == "prod_shared" + + http_client_mock.assert_requested( + "get", path=related_path, stripe_context="acct_child" + ) + + assert len(http_client_mock.get_all_calls()) == 2 + related_call = http_client_mock.get_last_call() + assert related_call.headers is not None + assert "Stripe-Account" not in related_call.headers diff --git a/tests/test_webhook.py b/tests/test_webhook.py index 2a884ef0a..7248ef01e 100644 --- a/tests/test_webhook.py +++ b/tests/test_webhook.py @@ -1,4 +1,5 @@ import time +from hashlib import sha256 import pytest @@ -35,12 +36,19 @@ def generate_header( - payload=DUMMY_WEBHOOK_PAYLOAD, secret=DUMMY_WEBHOOK_SECRET, timestamp=None + payload=DUMMY_WEBHOOK_PAYLOAD, + secret=DUMMY_WEBHOOK_SECRET, + timestamp=None, + debug_metadata=None, ): """Thin wrapper around WebhookSignature.generate_signature_header for tests.""" - return WebhookSignature.generate_signature_header( + header = WebhookSignature.generate_signature_header( payload, secret, timestamp ) + for key, value in (debug_metadata or {}).items(): + if value is not None: + header += f",{key}={value}" + return header def _build_header_with_scheme( @@ -214,6 +222,166 @@ def test_raise_on_no_valid_signatures_for_payload(self): DUMMY_WEBHOOK_PAYLOAD, header, DUMMY_WEBHOOK_SECRET ) + def test_diagnose_secret_mismatch(self): + dashboard_url_base = "https://dashboard.stripe.com/webhooks" + cases = [ + # Secret and masket secret don't match; show URL with endpoint + { + "masked_secret": "whsec_******************1q84", + "destination": "we_example", + "url": dashboard_url_base + "/we_example", + }, + # Missing and blank destinations use the bare Dashboard URL + { + "masked_secret": "whsec_******************1q84", + "destination": "", + "url": dashboard_url_base, + }, + # Length mismatch + {"masked_secret": "whsec_******************cret"}, + # An attacker-selected mask must not expose more than the last four characters + {"masked_secret": "whsec_*bcdefghijklmnopqrstuvwxyZ"}, + ] + for case in cases: + secret = case.get("secret", DUMMY_WEBHOOK_SECRET) + secret_suffix = case.get("secret_suffix", secret[-4:]) + masked_secret = case.get("masked_secret", "whsec_*******cret") + url = case.get("url", dashboard_url_base) + header = generate_header( + secret="whsec_other_secret", + debug_metadata={ + "secret": masked_secret, + "destination": case.get("destination"), + "payload": "00000000", + }, + ) + with pytest.raises(SignatureVerificationError) as error: + WebhookSignature.verify_header( + DUMMY_WEBHOOK_PAYLOAD, header, secret + ) + assert str(error.value) == ( + "Webhook signature verification failed. This request may not have originated from Stripe.\n\n" + f"The signing secret you provided is {len(secret)} characters long and ends in `{secret_suffix}`. " + f"However, the signing secret for this destination is {len(masked_secret)} characters long " + f"and looks like `{masked_secret}`. Ensure you're using the signing secret for this " + f"destination, as shown on the Dashboard: {url}\n\n" + "Learn more: https://docs.stripe.com/webhooks/signature" + ) + + def test_diagnose_payload_mismatch(self): + # User supplies the original body with an extra trailing space. + payload = DUMMY_WEBHOOK_PAYLOAD + " " + expected_hash = sha256( + DUMMY_WEBHOOK_PAYLOAD.encode("utf-8") + ).hexdigest()[-8:] + actual_hash = sha256(payload.encode("utf-8")).hexdigest()[-8:] + header = generate_header( + debug_metadata={ + "secret": "whsec_*******cret", + "payload": expected_hash.upper(), + } + ) + with pytest.raises(SignatureVerificationError) as error: + WebhookSignature.verify_header( + payload, header, DUMMY_WEBHOOK_SECRET + ) + assert str(error.value) == ( + "Webhook signature verification failed.\n\n" + "The request body you passed to this function differs from the request body sent by Stripe to this webhook destination.\n" + f"The SHA-256 hash of the body should end in `{expected_hash}`. However, the SHA-256 hash of the body you provided ends in `{actual_hash}`.\n\n" + "Make sure your code does not reformat or otherwise alter the raw HTTP request body before passing it to this function.\n\n" + "Learn more: https://docs.stripe.com/webhooks/signature" + ) + + def test_matching_metadata_falls_back_to_generic_error(self): + for masked_secret, secret in [ + ("whsec_*******cret", DUMMY_WEBHOOK_SECRET), + # Prefixes and mask widths do not change the fixed four-character comparison. + ("other_*******cret", DUMMY_WEBHOOK_SECRET), + ( + "whsec_*bcdefghijklmnopqrstuvwxyz", + "whsec_abcdefghijklmnopqrstuvwxyz", + ), + ("*", "*"), + ]: + header = generate_header( + secret="whsec_other_secret", + debug_metadata={"secret": masked_secret}, + ) + with pytest.raises(SignatureVerificationError) as error: + WebhookSignature.verify_header( + DUMMY_WEBHOOK_PAYLOAD, header, secret + ) + assert ( + str(error.value) + == "No signatures found matching the expected signature for payload" + ) + + def test_invalid_secret_metadata_falls_back_to_generic_error(self): + payload_hash = sha256( + DUMMY_WEBHOOK_PAYLOAD.encode("utf-8") + ).hexdigest()[-8:] + for masked_secret in [ + "unmasked", + "*" * 101, + "*\ud800", + # A blank first secret must not be replaced by a later value. + ",secret=whsec_*******abcd", + ]: + header = generate_header( + secret="whsec_other_secret", + debug_metadata={ + "secret": masked_secret, + "payload": payload_hash, + }, + ) + with pytest.raises(SignatureVerificationError) as error: + WebhookSignature.verify_header( + DUMMY_WEBHOOK_PAYLOAD, header, DUMMY_WEBHOOK_SECRET + ) + assert ( + str(error.value) + == "No signatures found matching the expected signature for payload" + ) + + def test_invalid_payload_metadata_falls_back_to_generic_error(self): + for payload_hash in [ + "1234567", + "123456789", + "not-hex!", + "a" * 101, + "1234567\ud800", + # A blank first hash must not be replaced by a later value. + ",payload=00000000", + ]: + header = generate_header( + secret="whsec_other_secret", + debug_metadata={ + "secret": "whsec_*******cret", + "payload": payload_hash, + }, + ) + with pytest.raises(SignatureVerificationError) as error: + WebhookSignature.verify_header( + DUMMY_WEBHOOK_PAYLOAD, header, DUMMY_WEBHOOK_SECRET + ) + assert ( + str(error.value) + == "No signatures found matching the expected signature for payload" + ) + + def test_valid_signature_ignores_conflicting_metadata(self): + header = generate_header( + debug_metadata={ + "secret": "*abcd", + "destination": "clidev_example", + "payload": "00000000", + } + ) + assert WebhookSignature.verify_header( + DUMMY_WEBHOOK_PAYLOAD, header, DUMMY_WEBHOOK_SECRET + ) + def test_raise_on_timestamp_outside_tolerance(self): header = generate_header(timestamp=int(time.time()) - 15) with pytest.raises(