docs: adding repo level claude.md - #149
Conversation
| - Log, `print`, or include in an error message any token, `code`, `code_verifier`, `client_secret`, DPoP private key, or full response body. There is no logger in the SDK — don't introduce one that emits these. | ||
| - Fail open. A validation, resolver, JWKS, or token-endpoint failure must raise, never fall through to a permissive default (no default domain, no "assume valid"). | ||
| - Validate `state` by comparing strings. `complete_interactive_login` looks the transaction up by `{transaction_identifier}:{state}` and raises `MissingTransactionError` on a miss — that store lookup *is* the binding. If you ever add a secret-to-secret comparison, use `hmac.compare_digest`, never `==`. | ||
| - Run `ruff format .` repo-wide — it is not a CI gate and the tree is not format-clean (13 files would change). Format only lines you touched. |
There was a problem hiding this comment.
The "13 files" count is a transcribed value that will go stale the moment someone runs ruff format on one file, and nothing in CI catches it. The src tree, the full ruff rule list, the Poetry 2.2.1 pin, and the 3.9-3.12 matrix have the same problem: they copy a value that already lives in config.
Shall we point at the command that produces the fact (poetry run ruff format --check .) and keep only the reasoning, so these can't drift?
|
|
||
| ## 5. `domain` may be a callable — resolve it, don't read it | ||
|
|
||
| MCD mode accepts `domain=<async resolver>` instead of a string. Any code path that builds a URL must |
There was a problem hiding this comment.
This MCD entry gives an agent a real recipe: resolve through _resolve_current_domain, thread store_options, fail closed. CTE, CIBA, and passkeys get no equivalent, so an agent works those flows cold.
Shall we add a short "to work on X, read these files" pointer for each complex flow instead of a full inline explanation?
|
|
||
| ### ⚠️ Ask First | ||
|
|
||
| - **Any breaking change — always ask first.** Never make one on your own initiative: a renamed/removed public method, a changed signature or default, a tightened model field, a new required constructor argument, or a raised Python floor. |
There was a problem hiding this comment.
This breaking-change list misses the error-code contract. The suite matches on a typed error's code, so renaming or removing an existing *ErrorCode breaks integrators even though it isn't a signature change.
Can we add it here so an existing code is treated as public API?
|
|
||
| | When this changes | Update these docs | | ||
| |-------------------|-------------------| | ||
| | A public method on `ServerClient` / `MyAccountClient` / `MfaClient` — added, renamed, or removed | `README.md` if it has a numbered section for the feature, **and** the matching `examples/*.md` guide | |
There was a problem hiding this comment.
This covers updating an existing examples/*.md guide, but not the case where a new feature has no guide yet.
Shall we add a line for creating one, modelled on a sibling guide and linked from README.md?
There was a problem hiding this comment.
My thought here would be - to add a CONVENTIONS.md for this kind of instructions and ask CLAUDE.md to always verify new code/examples with CONVENTIONS.md. Then we reduced the CLAUDE.md size and load the conventions on demand.
2 participants
Added
Changed