client: fail fast when the key lacks required capabilities

[goanpeca]

Summary

Use the SDK's capability check helper to validate the authorized key before dispatching each action verb, producing a clear failure when required capabilities are missing.

Why

Today a workflow learns about missing permissions only after an API call fails, often with a generic 401/403 from whichever operation happened first. The SDK already knows the authorized key's capabilities and can report exactly which capabilities are missing. That makes failures faster, clearer, and safer for destructive operations.

SDK support (already available)

• B2Client.hasCapabilities(required)
• Capability constants
• B2InsufficientCapabilityError
• AllowedInfo.capabilities from authorization

Proposed surface

No new input is required. Add an internal mapping from action verb to required capabilities and validate it after authorize() / before command dispatch. Examples:

• upload: writeFiles
• download/head/verify: readFiles
• list: listFiles
• presign: shareFiles
• delete/purge: deleteFiles
• retention: file retention/legal-hold capabilities depending on requested inputs

Acceptance criteria

• Each action verb declares the B2 capabilities it needs.
• Missing capabilities fail before the command starts with a message listing the missing names.
• Capability checks account for conditional inputs such as legal-hold, retention-mode, and bypass-governance.
• Existing successful workflows continue unchanged.
• Tests cover at least one read, write, share, delete, and retention capability failure.

Out of scope

• Emitting capabilities as outputs, tracked in client: expose granted capabilities and key scope as action outputs #114.
• Creating or managing application keys, tracked in keys: create, list, and delete scoped application keys #99.