errors

func ExitCode ¶

func ExitCode(err error) int

ExitCode maps any error to a stable exit code.

func NewAPI ¶

func NewAPI(message string, opts ...Option) error

NewAPI returns an API-category error.

func NewAuth ¶

func NewAuth(message string, opts ...Option) error

NewAuth returns an auth-category error.

func NewDiscovery ¶

func NewDiscovery(message string, opts ...Option) error

NewDiscovery returns a discovery-category error.

func NewInternal ¶

func NewInternal(message string, opts ...Option) error

NewInternal returns an internal-category error.

func NewValidation ¶

func NewValidation(message string, opts ...Option) error

NewValidation returns a validation-category error.

func PrintHuman ¶

func PrintHuman(w io.Writer, err error) error

PrintHuman writes a concise human-readable error rendering at normal verbosity.

func PrintHumanAt ¶ added in v1.0.5

func PrintHumanAt(w io.Writer, err error, v Verbosity) error

PrintHumanAt writes a human-readable error rendering at the given verbosity level.

func PrintJSON ¶

func PrintJSON(w io.Writer, err error) error

PrintJSON writes a machine-readable JSON error object.

func RejectCRLF ¶

func RejectCRLF(value, fieldName string) error

RejectCRLF rejects strings containing carriage return (\r) or line feed (\n). These characters enable MIME/HTTP header injection and must never appear in header field names, values, Content-ID, or filename parameters.

func RejectControlChars ¶

func RejectControlChars(value, flagName string) error

RejectControlChars rejects C0 control characters (except \t and \n) and dangerous Unicode characters from user input.

Control characters cause subtle security issues:

• Null bytes truncate strings at the C layer
• \r\n enables HTTP header injection
• Unicode Bidi characters allow visual spoofing (e.g. making "report.exe" display as "report.txt")

Tab and newline are allowed as they may appear in legitimate multi-line input.

func ResourceName ¶

func ResourceName(name string) error

func SafeInputPath ¶

func SafeInputPath(path string) (string, error)

SafeInputPath validates an upload/read source path for --file flags. It applies the same rules as SafeOutputPath — rejecting absolute paths, resolving symlinks, and enforcing working directory containment — to prevent an AI Agent from being tricked into reading sensitive files like /etc/passwd.

func SafeLocalFlagPath ¶

func SafeLocalFlagPath(flagName, value string) (string, error)

SafeLocalFlagPath validates a flag value as a local file path. Empty values and http/https URLs are returned unchanged without validation, allowing the caller to handle non-path inputs (e.g. API keys, URLs) upstream. For all other values, SafeInputPath rules apply. The original relative path is returned unchanged (not resolved to absolute) so upload helpers can re-validate at the actual I/O point via SafeUploadPath.

func SafeOutputPath ¶

func SafeOutputPath(path string) (string, error)

SafeOutputPath validates a download/export target path for --output flags. It rejects absolute paths, resolves symlinks to their real location, and verifies the canonical result is still under the current working directory. This prevents an AI Agent from being tricked into writing files outside the working directory (e.g. "../../.ssh/authorized_keys") or following symlinks to sensitive locations.

The returned absolute path MUST be used for all subsequent I/O to prevent time-of-check-to-time-of-use (TOCTOU) race conditions.

func SafePath ¶

func SafePath(path string) error

SafePath performs basic path validation checking for dangerous patterns. For full security (symlink resolution, CWD containment), use SafeOutputPath or SafeInputPath.

func StripQueryFragment ¶

func StripQueryFragment(path string) string

StripQueryFragment removes any ?query or #fragment suffix from a URL path. API parameters must go through structured --params flags, not embedded in the path, to prevent parameter injection and behaviour confusion.