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
• Temp files: never build a predictable path by string concatenation (e.g. "$tmpdir/prefix-$$-$name") and open it with a plain open/>. Use File::Temp::tempfile() (unpredictable name, exclusive O_EXCL creation) — the established pattern, first used in Document.pm's atomic save, and now also ImageConverter.pm's conversion output and AIComplete.pm's curl -K header file. A predictable name with no exclusive creation lets a local attacker who can guess the path (e.g. from a visible PID) pre-plant a symlink that gets followed and written through. If a temp file needs specific permissions tighter than the process default (e.g. secrets), set them atomically at creation with sysopen(..., O_CREAT|O_EXCL|O_WRONLY, $mode) rather than open followed by a later chmod — the gap between the two is a real window where the file exists at the wrong (more permissive) mode. A temp file holding a secret must also be deleted as soon as it's no longer needed (not left for the OS/tmp-cleaner to eventually reap) — AIComplete.pm unlinks its header file both on normal request completion and from a SIGTERM handler, since the editor cancels in-flight AI requests via signal on essentially every keystroke.
• Enforce discovery limits (Config.pm): 10,000 files max, 15 directory levels deep

Shell commands are limited to six places, all using safe list-form exec() or system() with argument arrays (no shell interpolation):

1. VCS integration (lib/Zepto/VCS/Git.pm): git commands via list-form open(FH, '-|') + exec('git', @args)
2. Clipboard tools (lib/Zepto/Terminal.pm): xclip / pbcopy / xsel / wl-copy via list-form pipes and exec()
3. File search (lib/Zepto/FileSearchEngine.pm): git grep, rg (ripgrep), grep via list-form open() and exec(). 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.
4. Image format conversion (lib/Zepto/ImageConverter.pm): sips (macOS) or convert (ImageMagick) via system() with argument arrays. Command detection uses backtick which but only for hardcoded literal commands, never user-supplied. The conversion output path is created via File::Temp::tempfile() (unpredictable name, exclusive O_EXCL-backed creation) — matching Document.pm's atomic-save pattern — so sips/convert can never be pointed at a pre-planted symlink.
5. Text transformation (lib/Zepto/Editor/Commands.pm cmd_transform, Alt+T): User-typed shell command piped to sh -c. This is an intentional capability — users consciously choose to run arbitrary shell commands on selected text, similar to a terminal. Not injection; users are explicitly requesting shell execution.
6. AI completion (lib/Zepto/AIComplete.pm): curl for requests to AI APIs via list-form fork+exec('curl', ...). Only enabled when user configures an API endpoint + key (disabled by default). The Authorization: Bearer <key> header is not passed as a -H argv token — process argv is visible to any local user via ps//proc/<pid>/cmdline for the curl child's whole lifetime, and this request fires repeatedly while typing. Instead, _child_http_request() writes header = "Authorization: Bearer <key>" to a short-lived temp file (File::Temp::tempfile(), same unpredictable-name + exclusive-creation pattern as Document.pm/ImageConverter.pm, plus chmod 0600) and passes it via curl -K <file>, deleting the file immediately after the request completes or is cancelled (including via the SIGTERM the editor sends to cancel an in-flight request on the next keystroke). See bugs.md and qa/40_regression_bugs.txt QA-REG-209.

Current mitigation strategy:

• All shell execution uses list-form pipes and exec(), never shell string interpolation
• This is fundamentally safer than string quoting because it eliminates the shell as an interpreter entirely
• User-controlled data (file paths, search patterns, etc.) never reaches the shell; they're passed as direct arguments to command invocations

Rules for new shell execution:

1. Use list-form open(my $fh, '-|', @cmd) + exec() or list-form system(@args) — never build command strings
2. Fixed commands only — never user-supplied command names
3. User-controlled data passed as arguments, not interpolated into command strings
4. Document the new location here with its purpose and approach
5. Flag for security review before merging

• 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 execution uses list-form pipes/system() — never shell string interpolation
• No new shell commands added without review and documentation in this file
• File permissions preserved on save
• No network calls introduced (except via AI completion, which must be opt-in with user config)
• Control characters from file content are neutralized before rendering
• Path operations stay within expected directories (use Cwd::realpath() to resolve symlinks)
• File size/depth limits respected

(No open items at this time)

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).