Skip to content

Omit API keys from StripeObject pickles and add explicit key rebinding 🪿✨ - #1959

Merged
zacchua-stripe merged 18 commits into
sdk-release/next-majorfrom
fix/pickle-credentials
Nov 10, 2026
Merged

zacchua-stripe merged 18 commits into
sdk-release/next-majorfrom
fix/pickle-credentials

Conversation

@zacchua-stripe

@zacchua-stripe zacchua-stripe commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Why?

Pickling StripeObjects currently persists API keys. This PR removes api key from pickling, replacing it with a placeholder and requires explicit reattachment before making requests through unpickled objects

What?

  • Serialize API_KEY_SERIALIZATION_CONSTANT instead of API keys.
  • Add reattach_api_key(api_key) to restore credentials. This also reattaches api keys to nested objects while preserving their connected accounts and API versions.
  • Reject requests before reattachment with an AuthenticationError. Checks run inside _APIRequestor before HTTP requests or per-call credential overrides.
  • Reject invalid keys and reattachment on normal or already reattached objects.

Before

customer = pickle.loads(trusted_cached_bytes)
customer.refresh()

After

# Not reattaching api key before using object
customer = pickle.loads(trusted_cached_bytes)
customer.refresh() # This would throw an AuthenticationError

# Reattaching api key more than once
customer = pickle.loads(trusted_cached_bytes)
customer.reattach_api_key(api_key)
customer.reattach_api_key(api_key) # This would throw a ValueError

# Reattaching to an object that was not unpickled
customer = stripe.Customer.retrieve("cus_123")
customer.reattach_api_key(api_key) # This would throw a ValueError

customer = pickle.loads(trusted_cached_bytes)
customer.reattach_api_key(api_key)
customer.refresh()

See Also

http://go/j/RUN_DEVSDK-3639

Configuration

  • skip-changefile: This PR is not a user-facing change, so there's no changefile.

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
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
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
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
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
Keep CI configuration unchanged to scope this branch to pickle credentials.

Committed-By-Agent: goose
Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280
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.
@zacchua-stripe
zacchua-stripe marked this pull request as ready for review October 30, 2026 23:34
@zacchua-stripe
zacchua-stripe requested a review from a team as a code owner October 30, 2026 23:34
@zacchua-stripe
zacchua-stripe requested review from jar-stripe and removed request for a team October 30, 2026 23:34
zacchua-stripe and others added 6 commits November 2, 2026 16:21
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 <noreply@anthropic.com>
Committed-By-Agent: claude
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Committed-By-Agent: claude
Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>
Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>
Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>

@jar-stripe jar-stripe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really close, but I think we need to make _requestor == None (or not None) the real check here; api_key is currently only set (afaict) on unpickling, so any json or other serialization/deserialization will fail (though json serialization does not serialize the api key).

One other path we didn't talk about is construct_from, which iiuc can accept an api key but maybe doesn't do the same thing with requestor that we expect. we should see if it needs to conform to these changes.

Comment thread .hark/migration-guides/v17.md Resolved
Comment thread stripe/_api_requestor.py Resolved
Comment thread stripe/_stripe_object.py Resolved
Comment thread tests/test_stripe_object.py Resolved
@jar-stripe

Copy link
Copy Markdown
Contributor

This is really close, but I think we need to make _requestor == None (or not None) the real check here; api_key is currently only set (afaict) on unpickling, so any json or other serialization/deserialization will fail (though json serialization does not serialize the api key).

One other path we didn't talk about is construct_from, which iiuc can accept an api key but maybe doesn't do the same thing with requestor that we expect. we should see if it needs to conform to these changes.

Actually, looking at this a bit more, I may have been too hasty here:

  data = json.loads(cached)  # from customer.to_dict(for_json=True)
  customer = stripe.Customer.construct_from(data, stripe.api_key)
  customer.refresh()

seems to do what we want, so maybe we can keep this scoped to only pickling. FFT note this and resolve my comments above this checks out.

@jar-stripe jar-stripe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good! I think the prose can still be edited a bit, but the code change looks right

Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>
@zacchua-stripe
zacchua-stripe changed the base branch from master to sdk-release/next-major November 6, 2026 18:02
zacchua-stripe and others added 3 commits November 6, 2026 11:10
Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>
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 <noreply@anthropic.com>
Committed-By-Agent: claude
@zacchua-stripe
zacchua-stripe enabled auto-merge (squash) November 10, 2026 19:35
@zacchua-stripe
zacchua-stripe merged commit 023a25c into sdk-release/next-major Nov 10, 2026
20 checks passed
@zacchua-stripe
zacchua-stripe deleted the fix/pickle-credentials branch November 10, 2026 21:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants