Stop logging the API key, and apply the log level and label settings

[zeevmoney]

Linear issues

• PER-16680: With logging enabled, the SDK wrote its API key to the log, and ignored the level, label and json log settings.

Why

With log={"enable": True}, creating a client (async Permit or permit.sync.Permit) logged json.dumps(config.dict()) at DEBUG. That dump includes token, and loguru's default stderr sink prints DEBUG, so the API key reached the log whatever log.level said. configure_logger() read only log.enable; level, label and json had no effect.

What changed

• The config dump is gone. Creating a client logs Permit SDK initialized: api_url=..., pdp=... at DEBUG.
• Every SDK log call goes through a new internal wrapper, permit/utils/sdk_logger.py. It drops records below log.level, replaces with [REDACTED] the API key of every client created in the process (longest key first, and the key without surrounding whitespace too), and puts [label] before the message. It logs with logger.opt(depth=2), so loguru still credits each record to the SDK module that logged it. The SDK adds no loguru sink and never calls logger.remove().
• read_error_body() redacts the PDP error body it returns. The body goes into both the SDK's error record and the PermitConnectionError raised by check, bulk_check and authorized_users.
• PermitConfig.token is declared with repr=False, so repr()/str() of a config, and tracebacks that print frame values (loguru's diagnose=True), do not show it.
• log.enable False calls logger.disable("permit"), as before. True calls logger.enable("permit") only to undo that call from an earlier client.
• wait_for_sync() yields a copy of the client whose PDP and API clients are rebuilt from the new config, through a _connect() hook the blocking client overrides. It no longer creates a new client, so it does not re-apply log settings.
• A ruff banned-api rule (TID251) flags loguru.logger anywhere in permit/ except the wrapper and permit/logger.py.
• The README gains a Logging section. The LoggerConfig docstring, its field descriptions and the configure_logger docstring describe the options as they now behave.

Behaviour changes

This is a bug and security fix inside 3.x, not an API break. It changes what users who enabled logs see.

• With log.enable True, creating a client no longer logs its config. 3.0.0 and earlier wrote the API key to the log at any configured level whenever log.enable was True. Users who ran that way should rotate those keys and purge those logs.
• Whatever the settings, the API key of every client in the process, and the same key without surrounding whitespace, is replaced with [REDACTED] in every message the SDK logs.
• A PermitConnectionError for a non-200 PDP response from check, bulk_check or authorized_users quotes the response body with the key replaced by [REDACTED].
• repr() and str() of PermitConfig no longer show token. The field, .dict() and .json() are unchanged.
• log.level now applies when log.enable is True: SDK records below it are dropped before any sink, and the application's own records and sinks are not affected. With the default "info", the SDK's DEBUG records no longer appear: HTTP request/response lines, check/authorized_users/get_user_permissions bodies, API context changes and the init line. Set "debug" to keep them. Accepted names are loguru's built-in levels in any case, the aliases warn and fatal, and levels the application added with logger.level(), matched by their exact name (or in any case if the application named the level in upper case). For an unknown name the SDK logs a warning that names it and uses INFO; before, any string was accepted and ignored.
• log.label now applies when log.enable is True: SDK messages start with [Permit] by default, or [<label>] . An empty label adds nothing.
• A client created with log.enable True after one created with logging disabled now logs; before, it stayed silent. The SDK calls logger.enable("permit") only in that case, so a logger.disable() the application made for permit or one of its modules still applies. When the SDK does undo its own disable, loguru also drops any permit.* disable made after that earlier client.
• The settings are process-wide, as loguru's logger is: the client created last decides whether the SDK logs, and the last one created with log.enable True sets the level and label.
• wait_for_sync() with proxy_facts_via_pdp yields a copy of the client (same class, own PDP and API clients) instead of a new client. It no longer re-applies log settings or logs the init line.
• log.log_as_json still has no effect. It is now documented as not applied, with the recipe: logger.remove(), then logger.add(sys.stderr, serialize=True).
• Unchanged: log.enable False (the default) calls logger.disable("permit"), prints nothing, and does not read level, label or json. An application that calls logger.enable("permit") itself still gets the SDK's records, now without the key.

Known limitations, not changed here:

• A user name and password written into the api_url or pdp URL are not redacted. The SDK's request lines logged them at DEBUG before this change too.
• Only PDP error bodies are redacted in exceptions. Errors built from REST API responses are not scrubbed.
• Two different keys that overlap at different positions in one string can leave a few characters of one of them.
• Redaction cost per log call grows with the number of distinct keys in the process: 0.6 us at 10 keys and 6.5 us at 100, on a 329-character check() message.

How it was tested

• tests/test_fix_logging.py: 53 offline tests. pytest_httpserver serves the PDP and REST API. Each test adds and removes its own sinks: a stderr sink in loguru's default format, read through capsys, and a JSON sink, both at DEBUG. An autouse fixture restores the SDK logger and loguru's permit switches. The tests cover:
  • the async and sync clients with level debug, info and unset, json on and off, through DEBUG, WARNING and ERROR records: no sentinel token and each record printed once;
  • a PDP that echoes the key back, in records and in raised errors (all three PDP paths, async and sync);
  • prefix keys, a trailing-space key, and empty or whitespace-only keys;
  • a logged traceback of a failed client creation with diagnose=True;
  • level filtering, unknown and app-added levels, label, and module attribution;
  • logging disabled;
  • the application's own disables surviving;
  • wait_for_sync() keeping log settings and sending X-Wait-Timeout/X-Timeout-Policy;
  • 40 clients adding no sinks.
• pytest -m "not e2e": 361 passed, 3 skipped on both the pydantic 2 and pydantic 1 lanes, warnings as errors, none raised (base: 305 passed, 3 skipped). tests/test_typing_surface.py: 3 passed on both lanes; the sync stub is unchanged.
• Mutation checks: each mutation was applied, the tests run, and the code restored. All were caught:
  • config dump restored as at the base: 25 tests fail, including every token test;
  • level check removed: 16 fail;
  • redaction removed: 5 fail;
  • label removed: 6 fail;
  • records credited to the wrapper (depth=0): 4 fail;
  • logger.disable dropped: 11 fail;
  • SDK-owned JSON sink: 9 fail;
  • a sink per client: 1 fails;
  • logger.remove(): 39 fail, 47 errors;
  • also caught: aliases removed, silent fallback on an unknown level, token registered only when enabled, repr=False removed, insertion-order and shortest-first redaction, untrimmed key only, scrub removed from error bodies, always/never logger.enable, the old wait_for_sync construction, a missing _connect, and a direct loguru import (flagged by ruff TID251).
• pre-commit (ruff ALL, ruff format, strict mypy, typos, uv lock --check) passes. mypy is clean on both lanes. actionlint is clean. zizmor reports no findings.
• e2e tests need a backend and keys: they were type-checked and collected (21 tests on both lanes) and run in CI.

Owner actions before merge

• Let CI run the e2e and compatibility lanes.
• log_as_json stays unapplied and documented for now; what it should do is decided separately.
• Release notes: state the key exposure in 3.0.0 and earlier, advise affected users to rotate keys and purge logs, and list the behaviour changes above.
• Update the docs repo (separate PR).

🤖 Generated with Claude Code

[linear-code]

PER-16680

[github-actions]

Dependency Security Audit

Scanned: pyproject.toml dependencies + dev group, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.