PathBuf::with_extension replaces everything after a component's last `.`,
silently discarding substituted metadata that legitimately contains a period
(e.g. "(feat. Somebody)" -> "(feat.ogg"). append_extension preserves the
final component verbatim and only ever appends.

[format] add UserError::UnsafeMetadata and reject fields that sanitize to "." or ".." to close a path-traversal hole bb73941167

Path::components() classifies a "." or ".." value as CurDir/ParentDir, not
Normal, so the existing NAME_MAX guard (which only inspects Normal
components) let such a value pass straight through to be resolved by the OS
as a real traversal segment at create_dir_all/rename time. reject_dot_components
runs on each field's fully-sanitized value, immediately after sanitize() and
before splicing it into the template, so it also catches values that only
become "."/".."/empty because of a later sanitize() transform.

[collection] add portable_filenames config flag and gate sanitize()'s reserved-punctuation table behind it 2d90ffe245

Threads a new opt-in portable: bool through sanitize()/substitute_tokens/
album_dir_path/track_dest_path so the seven NTFS/exFAT reserved characters
get replaced with their fullwidth Unicode counterpart only when
portable_filenames: true is set in collection.yml. Default stays false,
preserving byte-identical output_path for the common ext4-only case.

[format] strip bidi control characters unconditionally in sanitize() to close RTLO spoofing ddac324a41

U+202A-U+202E and U+2066-U+2069 are legal UTF-8 format characters that pass
through both a C0/C1 control-character filter and today's sanitize()
untouched, enabling RTLO extension-spoofing (MITRE ATT&CK T1036.002). Strip
them unconditionally, regardless of portable_filenames, since this is
security-relevant rather than a portability nicety. reject_dot_components
now also has to catch the case where this strip reduces a raw value to
exactly "." or "..".

[format] normalize substituted metadata to NFC before sanitizing e4eec8f11e

Adds the unicode-normalization crate (no std equivalent) and normalizes
each field to NFC as sanitize()'s first step, before any character-level
filtering. Already-NFC input (the common case) round-trips byte-identical.
Without this, two byte-distinct encodings of visually identical metadata
(e.g. Spotify returning NFD where a prior write used NFC) would produce
different output_path values for what a user considers the same track.

[format] add apply_portable_rules for whole-path-component device-name suffixing and trailing dot/space wrapping 99afd61dbf

Adds apply_portable_rules(relative: &Path, portable: bool) -> PathBuf,
called from album_dir_path and track_dest_path immediately after
substitute_tokens assembles the full relative path and before
check_name_max measures it. Runs once per relative path over
Component::Normal parts, unlike sanitize() which only ever sees one
field's isolated value — needed because the default track_format
combines {track_number:02} and {title} into a single component, so a
title of "CON" must not trigger device-name suffixing on its own.
A no-op when portable is false.

[download] fall back to NFC-normalized directory listing when output_path misses a direct exists() check f92759997e

Adds exists_normalized(path) -> bool, used by QueueEntry::for_track and
DownloadQueue::skip_existing in place of the direct .exists() call. ext4
is normalization-agnostic, so a file present under a differently-
normalized form of the same name (e.g. copied from an NFD-storing
source) was invisible to a byte-exact exists() check, causing a spurious
re-download of a track already on disk. The fallback only runs on a
direct miss, and never rewrites output_path — it only affects the
Skipped/not-Skipped decision.

changed mind: strip trailing run of periods and wrap in [] as fallback f396cc5d8e

[spec] remove historical decisions and rewrite to make it stateful bc388279ff

[ui] add sanitize_for_display and strip control characters at every metadata print site 8492335472

A raw title/artist/album containing a control character (ESC, CR, etc.)
was written to the terminal verbatim via crossterm's Print, enabling
window-title spoofing, cursor manipulation, and OSC/reply injection.

[ui] account for wide and zero-width characters in column-width truncation cee7513b0a

fit_chars/trunc_chars budgeted .chars().count(), treating every character
as one display column; a CJK-heavy title consumed roughly twice its
budgeted columns and broke the renderers' fixed-width row alignment.
Merge the two identical functions into src/ui/text.rs as a single
unicode-width-based implementation shared by every renderer.

[ui] pad title/artist cells by display column, not character count 7ec911f7a3

format!("{title:<width$}") pads by Unicode scalar count, so a truncated
CJK-heavy title (fewer characters but at its column budget) got padded
with extra spaces on top, overflowing its cell and shifting every column
printed after it. A wide enough overflow pushes the row past the
terminal width, causing the wrapped line to desync lines_drawn bookkeeping
and produce a waterfall of redrawn header lines on every tick.

Add pad_to_width (column-width-aware padding) to src/ui/text.rs and fold
it into display_title_artist, so both renderers print pre-padded,
column-exact cells instead of re-padding through Rust's format width.

[spec] post-implementation review 5e4837c0f9

[format] replace the per-field UnsafeMetadata check with a whole-relative-path 95ffea1e95

UnsafePathComponent check, run on the raw substituted string before it becomes a Path

Fixes an over-rejection bug where an unreferenced field (e.g. artist under the
default album_format/track_format, which never mentions {artist}) could block
enqueueing a track, and closes a more severe gap where a field sanitizing to an
empty string next to a template-literal '/' produced a leading/interior/trailing
empty path segment invisible to Path::components()-based guards — a leading
empty segment in particular lets root.join(...) discard the collection root
entirely, escaping to the real filesystem root with no '..' required.

reject_unsafe_path_segments now runs once per template, against the fully
assembled substituted string via str::split('/'), rather than per-field before
splicing. UserError::UnsafeMetadata is removed in favor of UnsafePathComponent.

[README] introduce portable_filenames config flag 17bef6c56a

[spec] second post-implementation review 3d455a9b10

[format] rewrite substitute_tokens as a single left-to-right scan over the template to stop one field's value from being re-scanned as another field's token, thread raw metadata values into the UnsafePathComponent message, and drop a redundant validate_format_tokens call a812b2a8e8

Claude-Session: https://claude.ai/code/session_018QUgLv6ZrEPyc3TUtoNwL2

[cleanup] reword comments to drop cross-references to spec Decisions/Test Specifications 0645223782

CLAUDE.md Principle VI prohibits comments that reference specification
artifacts, since a spec file is rewritten far more often than the code
that cites it and a stale cross-reference is worse than none. Restates
each comment's substance self-contained instead.

Claude-Session: https://claude.ai/code/session_018QUgLv6ZrEPyc3TUtoNwL2

[spec] propagate changes to core architecture b00b6d8491

[spec] deep dive on paths rewriting 65f300f375

maleszka added 1 commit

2026-07-14 17:45:04 +02:00

[spec] delete path-safety spec c56cbf8cde