Skip to content

feat(hex-ssh): Add structured transfer audit trail #37

@levnikolaevich

Description

@levnikolaevich

Context

ssh-upload and ssh-download now have stronger durability and safety semantics, but transfer observability still lags behind the stronger SSH competitors.

Today, users can see transfer summaries in tool output, but the server does not emit a structured transfer audit trail suitable for troubleshooting, compliance, or later analysis.

This should follow #38, so the audit event shape is informed by real backend behavior instead of mocks only.

Why after #38

  • interop results should inform which transfer details are stable enough to log as first-class fields
  • once real backend differences are known, the audit schema can avoid premature assumptions
  • audit is most useful after the current engine behavior is confirmed across real servers

What to do

  • Add opt-in transfer audit logging for ssh-upload and ssh-download
  • Record structured entries for:
    • source path
    • destination path
    • direction (upload/download)
    • bytes transferred
    • duration
    • verify mode
    • durability path
    • outcome (ok / error)
    • stable error code when available
  • Keep audit logging configurable and disabled by default
  • Ensure audit writes never break the transfer itself
  • Document the audit config and emitted fields

Schema/API changes

  • Add transfer audit configuration via env and/or package config
  • No tool input changes required
  • Define a stable audit event shape for transfer operations

Definition of Done

  • Upload and download emit structured audit records when enabled
  • Success and failure paths are both covered
  • Audit writes are best-effort and non-blocking for transfers
  • Sensitive data policy is documented
  • Tests cover event shape and failure isolation
  • README/docs describe how to enable and read transfer audit logs

Related issues

  • Depends on: #38
  • Parallel later value with: #39

Priority

Medium-high. This is the biggest remaining operational gap after hardening and interop validation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions