Zepto runs on users' desktops with read/write access to all their files. Users trust it. Security is non-negotiable.

This is a living document. Update it whenever security concerns are identified or mitigated.

• Check readability before operating: -r $path
• Preserve file permissions on save:

  my $perms = (stat($path))[2] & 07777;
  chmod($perms, $path);

• Do not follow symlinks outside the working directory without deliberate user action
• Validate that resolved paths stay within expected roots — no ../../../etc/passwd traversal
• Enforce discovery limits (Config.pm): 10,000 files max, 15 directory levels deep

Shell commands are limited to three places:

• VCS integration: git commands in lib/Zepto/VCS/Git.pm
• Clipboard tools: xclip / pbcopy / xsel / wl-copy in lib/Zepto/Terminal.pm
• File search: git grep, rg, grep in lib/Zepto/FileSearchEngine.pm

Rules:

• All user-controlled strings passed to the shell must be quoted with _shell_quote() or equivalent
• Prefer targeted git subcommands over generic shell pipelines
• Do not expand the set of shelled-out programs without security review

# Correct — safe
my $cmd = "git diff -- " . _shell_quote($path);

# Wrong — injectable
my $cmd = "git diff -- $path";

File search (lib/Zepto/FileSearchEngine.pm):

• Commands: git grep, rg (ripgrep), grep — for cross-file text search
• Quoting: list-form open(my $fh, '-|', @cmd) — no shell interpolation; search pattern passed via -e flag as a direct argument, never interpolated into a string
• Scope directory validated with -d before use
• Results are display-only until user explicitly selects one to open

If a new shell exec is needed, it must:

1. Accept only a fixed command with quoted arguments — never a user-supplied command string
2. Be documented here with its purpose and quoting approach

• Terminal escape sequences in file content must be stripped or neutralized before display — a crafted file must not be able to hijack the terminal
• Box-drawing characters and UI escape sequences come from trusted constants only (never from file content)
• ANSI color codes from file content must not pass through to the terminal unescaped

• Use Unicode codepoints (\x{XXXX}) — never raw byte strings like "\xe2\x94\x82"
• Add use utf8 to any file containing Unicode literals
• Encode before final output: utf8::encode($output) if utf8::is_utf8($output)
• Never use length() for display width — it returns character count, not column width; CJK and combining characters break naive length assumptions

• Clipboard content from the OS is untrusted user input — never auto-execute it
• Paste inserts content as literal text into the buffer — no interpretation, no execution

Run through this before committing any change that touches file I/O, shell execution, or rendering:

• All shell-interpolated paths are quoted with _shell_quote()
• No new shell commands added without review
• File permissions preserved on save
• No network calls introduced
• Control characters from file content are neutralized before rendering
• Path operations stay within expected directories
• File size/depth limits respected

When an item above is investigated and resolved, document the finding and remove it from this list (or move to bugs.md if it becomes a tracked bug).

Users may run any Perl version shipped with their OS. We cannot require upgrades — instead we avoid dangerous patterns and minimize exposure.

Last reviewed: 2026-03-02

1. Never construct qr// or tr// from file content. User-typed find patterns are acceptable (self-inflicted risk). But never programmatically compile regexes or transliterations derived from an opened file — that turns a "user opens untrusted file" scenario into a code execution vector.
2. Keep all tr// patterns as string literals. No dynamic construction.
3. Never use string eval with file-derived content. The eval "require $class" in Highlighter.pm is acceptable only because $class comes from a hardcoded mapping.
4. Treat file content as higher risk than keyboard input. A user typing a crafted regex is attacking themselves. A file silently triggering an overflow on open is an actual exploit. Design accordingly — file content should never reach regex compilation, tr//, or eval.

1. What Perl feature is affected? (regex, tr//, IO layers, specific module, etc.)
2. Does Zepto use it? grep -rn 'pattern' lib/ build.pl
3. Can file content reach it? File content reaching the vulnerable path = real risk. User keyboard input reaching it = low risk (self-inflicted). Hardcoded literals reaching it = no risk.
4. Add to the table above with the risk assessment. Add defensive rules if needed.

Where to check: Perl release deltas (perldoc.perl.org), CPANSec (security.metacpan.org), NVD (nvd.nist.gov).