From d97a68e28ec6553c3545fdf7e5322e871559cfdb Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Thu, 5 Nov 2026 14:50:49 -0800 Subject: [PATCH 1/8] Add Canary CI workflow sharing CI steps through local actions (#1967) Move the static checks, build, and test steps into composite actions used by both CI and a new Canary CI workflow. Canary CI runs on pushes to the canary-ga, canary-beta, and canary-private-preview branches, points stripe-mock at the matching canary specs and fixtures, and has no publish job. CI job names are unchanged, so required status checks still match. Committed-By-Agent: claude Co-authored-by: Claude Opus 5.5 --- .github/actions/build-package/action.yml | 15 ++++ .github/actions/static-checks/action.yml | 29 +++++++ .github/actions/test/action.yml | 100 +++++++++++++++++++++++ .github/workflows/canary.yml | 89 ++++++++++++++++++++ .github/workflows/ci.yml | 49 +---------- 5 files changed, 237 insertions(+), 45 deletions(-) create mode 100644 .github/actions/build-package/action.yml create mode 100644 .github/actions/static-checks/action.yml create mode 100644 .github/actions/test/action.yml create mode 100644 .github/workflows/canary.yml 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 From e9f0e8593d90e1a579364d168208f8475cf575ec Mon Sep 17 00:00:00 2001 From: jar-stripe Date: Fri, 6 Nov 2026 16:44:31 -0800 Subject: [PATCH 2/8] Fix stale Stripe-Account header on directly-retrieved Event related objects (#1968) * Fix stale Stripe-Account header on directly-retrieved Event related objects A directly-retrieved v2 Event keeps the requestor of whatever account fetched it, so Event.fetch_related_object() could send a stale Stripe-Account header alongside the event's own Stripe-Context. EventNotification already avoids this in its own construction via StripeClient.with_stripe_context; give Event the same treatment where it's deserialized in _convert_to_stripe_object. Fixes RUN_DEVSDK-3694. Co-Authored-By: Claude Sonnet 5 Committed-By-Agent: claude * Update requestor context handling in _util.py Refactor handling of requestor context for v2 events. --------- Co-authored-by: Claude Sonnet 5 --- ...t-related-object-account-scoping.change.md | 6 ++ stripe/_api_requestor.py | 19 ++++++ stripe/_util.py | 13 ++++ tests/test_api_requestor.py | 31 ++++++++++ tests/test_v2_event.py | 60 +++++++++++++++++++ 5 files changed, 129 insertions(+) create mode 100644 .hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md diff --git a/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md b/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md new file mode 100644 index 000000000..027e2fb54 --- /dev/null +++ b/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md @@ -0,0 +1,6 @@ +--- +title: Fix stale Stripe-Account header when fetching an object related to a directly-retrieved Event +semver_level: patch +jira_tickets_closed: +- RUN_DEVSDK-3694 +--- diff --git a/stripe/_api_requestor.py b/stripe/_api_requestor.py index 6224c5e6d..a9a52c09d 100644 --- a/stripe/_api_requestor.py +++ b/stripe/_api_requestor.py @@ -65,6 +65,7 @@ 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"] @@ -174,6 +175,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 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/tests/test_api_requestor.py b/tests/test_api_requestor.py index 744930ed9..b8adae3a3 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_v2_event.py b/tests/test_v2_event.py index 7f59ca3d5..ea7c46c95 100644 --- a/tests/test_v2_event.py +++ b/tests/test_v2_event.py @@ -15,6 +15,7 @@ V1BillingMeterErrorReportTriggeredEvent, ) from stripe.events._v1_product_updated_event import ( + V1ProductUpdatedEvent, V1ProductUpdatedEventNotification, ) from stripe.v2.core._event import ( @@ -515,3 +516,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 From ee9db3377090cd2eb7c9a338b943c1fdf97a67f8 Mon Sep 17 00:00:00 2001 From: jar-stripe Date: Mon, 9 Nov 2026 10:05:09 -0800 Subject: [PATCH 3/8] Reject CR/LF/NUL in header values before passing them to pycurl (#1971) PycurlClient built the HTTPHEADER list via raw "%s: %s" string interpolation with no validation, so a header value containing CR or LF could inject an additional header line (e.g. via Stripe-Request- Trigger, built from an unverified webhook event id). Other HTTP client backends in this file are already protected by their own underlying library (stdlib http.client, h11, aiohttp); pycurl has no such check built in, so it needs one here. Committed-By-Agent: claude Co-authored-by: Claude Sonnet 5 --- ...ar_reject-pycurl-header-injection.change.md | 6 ++++++ stripe/_http_client.py | 18 ++++++++++++++++++ tests/test_http_client.py | 17 +++++++++++++++++ 3 files changed, 41 insertions(+) create mode 100644 .hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md diff --git a/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md b/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md new file mode 100644 index 000000000..401ef8606 --- /dev/null +++ b/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md @@ -0,0 +1,6 @@ +--- +title: "Reject header values containing CR, LF or NUL in the pycurl HTTP client" +semver_level: patch +jira_tickets_closed: +- RUN_DEVSDK-3683 +--- diff --git a/stripe/_http_client.py b/stripe/_http_client.py index 65c3ed684..6f0815e91 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"] @@ -957,6 +974,7 @@ def _request_internal( self._curl.setopt(self.pycurl.NOSIGNAL, 1) self._curl.setopt(self.pycurl.CONNECTTIMEOUT, 30) self._curl.setopt(self.pycurl.TIMEOUT, 80) + _assert_no_header_injection(headers) self._curl.setopt( self.pycurl.HTTPHEADER, ["%s: %s" % (k, v) for k, v in dict(headers).items()], diff --git a/tests/test_http_client.py b/tests/test_http_client.py index 8b3ab71fb..0c6eaa557 100644 --- a/tests/test_http_client.py +++ b/tests/test_http_client.py @@ -1149,6 +1149,23 @@ 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) + class TestPycurlClientHttpProxy(TestPycurlClient): PROXY = "http://user:withPwd@slap:8888/" From 0291a9a4023f21473c2d30daa3560eb55eb5b53d Mon Sep 17 00:00:00 2001 From: Christopher Orr Date: Mon, 9 Nov 2026 21:59:48 +0100 Subject: [PATCH 4/8] Add error messages to help users debug signature verification failures. (#1958) The stripe-signature header may now include additional metadata about the event destination and the event being sent. These can help narrow down the reason why signature verification failed. No changes are made to the verification process; this just updates how error messages are generated, if the metadata is present in the header. --- ...rc_webhook-signature-diagnostics.change.md | 6 + stripe/_webhook.py | 100 +++++++++- tests/test_webhook.py | 172 +++++++++++++++++- 3 files changed, 274 insertions(+), 4 deletions(-) create mode 100644 .hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md diff --git a/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md b/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md new file mode 100644 index 000000000..af73a3475 --- /dev/null +++ b/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md @@ -0,0 +1,6 @@ +--- +title: Improve webhook signature verification error messages +semver_level: patch +--- + +- When diagnostic metadata is present in the `Stripe-Signature` header, error messages help identify an incorrect signing secret or altered request body. 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/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( From e881f4ad3d63df52c2adb4111fe2ee0a1fe986f4 Mon Sep 17 00:00:00 2001 From: Ramya Rao <100975018+ramya-stripe@users.noreply.github.com> Date: Tue, 10 Nov 2026 11:53:20 -0800 Subject: [PATCH 5/8] Remove obsolete guidance for updating CA bunle (#1973) * Remove update-certs task from justfile Removed the update-certs task from the justfile. * Remove CA certificates update instructions from README Removed instructions for updating bundled CA certificates. --- README.md | 6 ------ justfile | 3 --- 2 files changed, 9 deletions(-) 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: From 023a25c06a20f69859e8c10272466b702fdd3c2f Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Tue, 10 Nov 2026 13:54:12 -0800 Subject: [PATCH 6/8] =?UTF-8?q?Omit=20API=20keys=20from=20StripeObject=20p?= =?UTF-8?q?ickles=20and=20add=20explicit=20key=20rebinding=20=F0=9F=AA=BF?= =?UTF-8?q?=E2=9C=A8=20(#1959)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [🪿] Omit API keys from StripeObject pickles Prevent credentials from leaking into pickle-backed caches and queues. Add graph-wide set_api_key() binding so consumers can supply their own credentials while preserving routing and destination-global fallback. Include regression tests and v16 migration guidance. Existing stored pickles remain sensitive and are not sanitized by this change. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] try to deslop Consolidate overlapping pickle round-trip and credential-rebinding tests to remove duplicate setup and serialization. Retain coverage for supported pickle protocols, destination-global fallback, nested rebinding, routing preservation, and credential-free re-pickling without changing implementation behavior. Verified 172 targeted tests pass, along with formatting, linting, and git diff whitespace checks. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Align pickle credential migration with v17 Document global fallback and explicit recursive key rebinding. Strengthen nested requestor preservation coverage and remove task-specific README edits. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] try to deslop Remove redundant nested-resource serialization and assertions already covered by payload equality and credential-absence checks on re-pickled bytes. Recursive rebinding, cycle handling, routing preservation, standalone metadata serialization, and request-boundary coverage remain intact. Validated with 101 passing StripeObject tests, formatting, linting, and git diff --check. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Update PyPI publishing action to v1.14.3 Fix the workflow security check failing on GHSA-5xjx-3w67-w9x9. Pin the patched release to its verified commit SHA. https: //github.com/advisories/GHSA-5xjx-3w67-w9x9 Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Revert unrelated PyPI publishing action upgrade Keep CI configuration unchanged to scope this branch to pickle credentials. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Update pickle credential changefile wording and filename * [🪿] Simplify v17 pickle migration guidance Use concise examples to explain explicit API-key rebinding and global fallback. Clarify that rebinding preserves current requestor configuration, not the producer's custom HTTP client. * [🪿] Replace set_api_key with per-call API keys on instance methods Remove StripeObject.set_api_key() and instead accept an api_key on the instance methods that previously could not take one: refresh(), refresh_async(), save(), and auto_paging_iter() on ListObject, SearchResultObject, and their V2 equivalents. delete() and generated instance methods already accept per-call request options. Co-Authored-By: Claude Opus 5.5 Committed-By-Agent: claude * [🪿] Trim pickle credential changefile wording Co-Authored-By: Claude Opus 5.5 Committed-By-Agent: claude * Require explicit API key reattachment after unpickling Committed-By-Agent: codex Co-authored-by: codex * Keep serialized placeholders in requestors and guard requests centrally Committed-By-Agent: codex Co-authored-by: codex * Clarify API key reattachment wording in changefile Committed-By-Agent: codex Co-authored-by: codex * Clarify API key reattachment migration guidance Committed-By-Agent: codex Co-authored-by: codex * Address serialization documentation review feedback Committed-By-Agent: codex Co-authored-by: codex * Make migration guide before/after examples equivalent Keep the Before and After snippets identical apart from the reattach step, and move the list/event usage into a separate example. Co-Authored-By: Claude Opus 5.5 Committed-By-Agent: claude --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: codex --- ...30_zacchua_omit-pickled-api-keys.change.md | 7 + .hark/migration-guides/v17.md | 37 ++ stripe/_api_requestor.py | 13 + stripe/_stripe_object.py | 49 ++- tests/api_resources/test_list_object.py | 91 +++++ tests/api_resources/test_list_object_v2.py | 28 ++ .../test_search_result_object.py | 30 ++ tests/test_stripe_object.py | 373 +++++++++++++++++- tests/test_v2_event.py | 28 ++ 9 files changed, 636 insertions(+), 20 deletions(-) create mode 100644 .hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md create mode 100644 .hark/migration-guides/v17.md diff --git a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md new file mode 100644 index 000000000..76dc33045 --- /dev/null +++ b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md @@ -0,0 +1,7 @@ +--- +title: Omit API keys from pickled StripeObjects +semver_level: major +--- +StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. + +See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. diff --git a/.hark/migration-guides/v17.md b/.hark/migration-guides/v17.md new file mode 100644 index 000000000..a7a654b8c --- /dev/null +++ b/.hark/migration-guides/v17.md @@ -0,0 +1,37 @@ +# Migration guide for v17 +## API keys are no longer preserved in pickled StripeObjects +This affects integrations that persist StripeObjects in caches or queues and then make requests through the restored objects. + +Pickling now replaces API keys with a placeholder, including on nested objects. Unpickled objects retain their data, connected-account routing, and API version but have no API key. Before making requests through an unpickled object, call `reattach_api_key()` with a key from secure configuration: + +```python +# Before +customer = pickle.loads(trusted_cached_bytes) +customer.refresh() + +# After +customer = pickle.loads(trusted_cached_bytes) +customer.reattach_api_key(api_key) +customer.refresh() +``` + +Reattach the API key the same way on unpickled lists and events before making requests through them: + +```python +customers = pickle.loads(trusted_cached_list_bytes) +customers.reattach_api_key(api_key) +for customer in customers.auto_paging_iter(): + ... + +event = pickle.loads(trusted_cached_event_bytes) +event.reattach_api_key(api_key) +related_object = event.fetch_related_object() +``` + +`reattach_api_key()` also attaches API keys to nested unpickled objects. Each retains its saved API version and connected account. Nested objects that already have an API key keep it. Reattachment does not change `stripe.api_key`, and pickling the object again omits the reattached key. + +Requests before reattachment raise `AuthenticationError` with instructions to call `reattach_api_key()`, even if you set a global or per-call API key. + +Calling `reattach_api_key()` more than once, or on an object whose API key wasn't replaced with the serialization placeholder, raises `ValueError`. Passing an empty key or the serialization placeholder also raises `ValueError`. + +This behavior applies to pickles created with v17. Pickles created with earlier versions can still contain API keys. Remove or replace those stored pickles according to your application's storage policy. diff --git a/stripe/_api_requestor.py b/stripe/_api_requestor.py index 6224c5e6d..9d0bd36e6 100644 --- a/stripe/_api_requestor.py +++ b/stripe/_api_requestor.py @@ -61,6 +61,7 @@ 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 @@ -165,6 +166,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: @@ -673,6 +680,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/_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/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_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 7f59ca3d5..7353821ff 100644 --- a/tests/test_v2_event.py +++ b/tests/test_v2_event.py @@ -1,4 +1,6 @@ import json +import pickle +import stripe from typing import Any, Callable, Dict, Optional, Union from typing_extensions import assert_type @@ -38,6 +40,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( From 22e7da79a337b81345b86723416b8b94a28b2359 Mon Sep 17 00:00:00 2001 From: Zachary Chua Date: Wed, 11 Nov 2026 11:53:13 -0800 Subject: [PATCH 7/8] Bump version to 17.0.0 --- ...10-12_orrc_webhook-signature-diagnostics.change.md | 1 + ...2026-10-30_zacchua_omit-pickled-api-keys.change.md | 2 ++ ...fix-event-related-object-account-scoping.change.md | 1 + ...11-06_jar_reject-pycurl-header-injection.change.md | 3 ++- .hark/releases.json | 6 ++++++ CHANGELOG.md | 11 +++++++++++ VERSION | 2 +- pyproject.toml | 2 +- stripe/_version.py | 2 +- 9 files changed, 26 insertions(+), 4 deletions(-) diff --git a/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md b/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md index af73a3475..7e037e3ca 100644 --- a/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md +++ b/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md @@ -1,6 +1,7 @@ --- title: Improve webhook signature verification error messages semver_level: patch +released_in_version: 17.0.0 --- - When diagnostic metadata is present in the `Stripe-Signature` header, error messages help identify an incorrect signing secret or altered request body. diff --git a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md index 76dc33045..3642fa3ee 100644 --- a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md +++ b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md @@ -1,7 +1,9 @@ --- title: Omit API keys from pickled StripeObjects semver_level: major +released_in_version: 17.0.0 --- + StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. diff --git a/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md b/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md index 027e2fb54..a42be97cd 100644 --- a/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md +++ b/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md @@ -3,4 +3,5 @@ title: Fix stale Stripe-Account header when fetching an object related to a dire semver_level: patch jira_tickets_closed: - RUN_DEVSDK-3694 +released_in_version: 17.0.0 --- diff --git a/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md b/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md index 401ef8606..5a9f7a446 100644 --- a/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md +++ b/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md @@ -1,6 +1,7 @@ --- -title: "Reject header values containing CR, LF or NUL in the pycurl HTTP client" +title: Reject header values containing CR, LF or NUL in the pycurl HTTP client semver_level: patch jira_tickets_closed: - RUN_DEVSDK-3683 +released_in_version: 17.0.0 --- diff --git a/.hark/releases.json b/.hark/releases.json index 4f4653e70..9a4449ef1 100644 --- a/.hark/releases.json +++ b/.hark/releases.json @@ -4,6 +4,12 @@ "channel": "ga" }, "releases": [ + { + "version": "17.0.0", + "released_on": "2026-11-11", + "pinned_api_version": "2026-10-28.endive", + "minimum_runtime_version": "3.9" + }, { "version": "16.1.0", "released_on": "2026-10-29", diff --git a/CHANGELOG.md b/CHANGELOG.md index ba20189c7..168094b29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ Instead, edit a corresponding `.change.md` file and run `hark build`. # Changelog +## 17.0.0 - 2026-11-11 +* Improve webhook signature verification error messages + - When diagnostic metadata is present in the `Stripe-Signature` header, error messages help identify an incorrect signing secret or altered request body. +* ⚠️ Omit API keys from pickled StripeObjects + + StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. + + See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. +* Fix stale Stripe-Account header when fetching an object related to a directly-retrieved Event +* Reject header values containing CR, LF or NUL in the pycurl HTTP client + ## 16.1.0 - 2026-10-29 This release changes the pinned API version to `2026-10-28.endive`. diff --git a/VERSION b/VERSION index e0228cf18..aac58983e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -16.1.0 +17.0.0 diff --git a/pyproject.toml b/pyproject.toml index 638bb9092..60e87b3a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "stripe" -version = "16.1.0" +version = "17.0.0" readme = "README.md" description = "Python bindings for the Stripe API" authors = [{ name = "Stripe", email = "support@stripe.com" }] diff --git a/stripe/_version.py b/stripe/_version.py index ca9fc3dc4..cf692abbb 100644 --- a/stripe/_version.py +++ b/stripe/_version.py @@ -1 +1 @@ -VERSION = "16.1.0" +VERSION = "17.0.0" From 38d853bcca96a22796a496705455ea18e2558a2e Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Wed, 11 Nov 2026 12:15:03 -0800 Subject: [PATCH 8/8] Use a separate Curl handle per thread in PycurlClient (#1972) PycurlClient created one pycurl.Curl handle in its constructor and reconfigured it for every request with no synchronization. When one client was shared across threads, concurrent requests could overwrite each other's URL, body, and headers, sending one request with another request's API key and Stripe-Account. Each thread now lazily creates its own handle in the client's existing thread-local storage, so connections are still reused within a thread. close() closes the current thread's handle. Closes RUN_DEVSDK-3704 Committed-By-Agent: claude Co-authored-by: Claude Opus 5.5 --- ...cchua_pycurl-thread-local-handle.change.md | 6 + stripe/_http_client.py | 60 +++++---- tests/test_http_client.py | 114 ++++++++++++++++++ 3 files changed, 158 insertions(+), 22 deletions(-) create mode 100644 .hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md diff --git a/.hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md b/.hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md new file mode 100644 index 000000000..f28c8faf3 --- /dev/null +++ b/.hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md @@ -0,0 +1,6 @@ +--- +title: "Use a separate Curl handle per thread in PycurlClient so concurrent requests can't overwrite each other's URL, body, or headers" +semver_level: patch +jira_tickets_closed: +- RUN_DEVSDK-3704 +--- diff --git a/stripe/_http_client.py b/stripe/_http_client.py index 6f0815e91..51740e156 100644 --- a/stripe/_http_client.py +++ b/stripe/_http_client.py @@ -871,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 @@ -886,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 {} @@ -944,48 +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) + 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) + 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) - self._curl.setopt( + 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) @@ -995,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 @@ -1044,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/tests/test_http_client.py b/tests/test_http_client.py index 0c6eaa557..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 @@ -1166,6 +1167,119 @@ def test_request_rejects_header_injection( 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/"