fix: omit static Stream header when HTTP auth is supplied

[manana2520]

Summary

Omit X-StorageApi-Token in StreamClient when the caller explicitly supplies http_auth, matching the existing Storage client contract. Previously StreamClient added the static header even in bearer mode, including empty/sentinel/stale-token values; a competing header could cause HTTP401 while the bearer credential itself was valid.

One constructor guard fixes direct StreamClient calls and the KeboolaClient stream sub-client. Static-token behavior and default CLI/facade session guards remain unchanged; no new session-support surface or version bump.

Evidence

• Real EU GCP project read-only comparison: configured static-header request401; explicit session bearer with no static header200. No credential rotation or production mutation.
• Six regression cases (direct and facade sub-client × empty/sentinel/static token arguments) fail before the fix and pass after. Tests assert header ABSENCE, not merely falsiness, and preserve the project header.
• Patched SDK read-only source listing200; three sources returned. No secrets/raw source objects persisted in evidence.
• make check passed: 6574 passed,12 skipped; lint,format,typecheck and repository gates green. Existing warnings retained.
• git diff --check passed.

The configured static token's independent rejection is not fixed/hidden by this change. Explicit bearer auth remains caller-supplied, never an implicit auth fallback.

Plugin sync: no command/signature/permission changes; added a vNEXT low-level auth gotcha, explicitly retaining CLI/public facade guards. No release/changelog edits.

Self-review: main-agent code/test/call-site review completed. /kbagent:review plugin review skipped: unavailable in this Pi session; no independent-review claim. No live E2E mutation suite run against the user's project.

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 3/5) · profile keboola-mcp-server

placeholder

Concerns:

• src/keboola_agent_cli/stream_client.py: Bearer-path requests now omit X-StorageApi-Token — auth-surface behavior change

[manana2520]

Follow-up docs correction pushed as 2d1ca569be977e4ba0bf0f7bc337ed66bf60231e (no additional SDK behavior change).

The bundled Stream gotcha said no master-token requirement. The current authoritative tutorial explicitly requires the personal master token of a project user with role Admin for Stream writes:
https://help.keboola.com/storage/data-streams/tutorial/

A read-only investigation through native kbagent and token verification found an important distinction: isMasterToken, canManageBuckets, and canManageTokens can all be true while the bound project role is share; Stream writes reject that identity with403 while reads work. The gotcha now distinguishes the normal Storage auth header from the required project-user role, warns against automatic promotion/credential substitution, and does not invent an error code. Explicit source/sink IDs remain documented optional fields, not evidence of a different auth gate.

Docs-only validation: git diff --check and make version-gate-check passed. The earlier6574-pass/12-skip full result belongs to the preceding code checkpoint; exact-head remote CI should be read separately. No version bump, installed CLI update, project permission change or write retry was performed.