Skip to content

docs: secret key rotation, token safety, salt clarification, deprecate key_derivation="none" - #1

Open
GazingInSpring wants to merge 1 commit into
mainfrom
worktree-agent-affde5923d7e624fc
Open

docs: secret key rotation, token safety, salt clarification, deprecate key_derivation="none"#1
GazingInSpring wants to merge 1 commit into
mainfrom
worktree-agent-affde5923d7e624fc

Conversation

@GazingInSpring

Copy link
Copy Markdown
Owner

Summary

Documentation and deprecation pass covering secret key rotation, unsafe token handling, and salt behaviour. All 297 tests pass.

Changes

docs/concepts.rst

  • "The Secret Key" — added guidance on replacing the entire key for immediate invalidation (compromise scenario) vs. appending to the rotation list for graceful rollover; added security note that signed tokens are credentials and must not be logged or exposed in error responses.
  • "The Salt" — added .. warning:: block clarifying that the salt is a static, deterministic context label (not per-token randomness / not a nonce or IV), and that key_derivation="none" silently ignores it, defeating context separation.
  • "Key Rotation" — added note that SignatureExpired is raised immediately regardless of rotation list length; key rotation does not extend a token's lifetime.

docs/serializer.rst

  • Added .. warning:: before the loads_unsafe example: never act on an unauthenticated payload in production; never use with pickle or any code-executing deserialiser.

docs/signer.rst

  • Added .. warning:: after .. autoclass:: NoneAlgorithm: tokens have no signature, do not use in production.

src/itsdangerous/signer.py

  • Deprecated key_derivation="none": emits DeprecationWarning on use.
  • Added "none" (with deprecation note) to the key_derivation parameter docstring and default_key_derivation class-attribute comment.
  • Updated NoneAlgorithm docstring to state explicitly that tokens offer no authenticity guarantee.
  • Added import warnings.

tests/test_itsdangerous/test_signer.py

  • Removed "none" from the test_key_derivation parametrize list.
  • Added test_key_derivation_none_deprecated asserting DeprecationWarning is raised (inherited by TestTimestampSigner via class hierarchy — no changes needed in test_timed.py).

CHANGES.rst

  • Four new bullets under Unreleased: SignatureExpired rotation behaviour, key replacement guidance, token-credential security note, key_derivation="none" deprecation.

@GazingInSpring
GazingInSpring force-pushed the worktree-agent-affde5923d7e624fc branch 6 times, most recently from 216c40f to c2fa727 Compare May 27, 2026 22:04
@GazingInSpring
GazingInSpring force-pushed the worktree-agent-affde5923d7e624fc branch from c2fa727 to 58c4a75 Compare May 27, 2026 22:19
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