Skip to content

docs: say what the path and input checks do - #93

Merged
kkdev92 merged 1 commit into
mainfrom
docs/security-claims
Oct 3, 2026
Merged

kkdev92 merged 1 commit into
mainfrom
docs/security-claims

Conversation

@kkdev92

@kkdev92 kkdev92 commented Oct 3, 2026

Copy link
Copy Markdown
Owner

Makes SECURITY.md describe the path and input checks as the code does them.

Why

SECURITY.md said that the save directory "cannot be absolute or contain .." and that file name patterns "cannot contain shell metacharacters". Neither is refused: validateSaveDirectory and validateFileNamePattern feed the configuration warnings in the ClipShot log. The protection is real but elsewhere, and the page should point at it rather than at the warnings.

  • src/image/file-writer.ts calls validatePathInsideWorkspace on the target file before writing it (writeAtomic) and on a folder before creating it (ensureDir).
  • validatePathInsideWorkspace resolves the workspace root and the existing part of the target through realpath, then refuses a path whose relation to the root starts with .. or is absolute.
  • The save path is path.join(workspaceRoot, saveDirectory, fileName) (src/image/path-generator.ts), so a .. that stays inside the workspace resolves to the folder it names.
  • sanitizeFileName (src/security/sanitizer.ts) removes control characters and < > : " / \ | ? * from each generated name, and on Windows prefixes a reserved name; it leaves other shell metacharacters, which only the warning reports.

Change

  • Path Traversal Prevention: the saved image and the folders created for it are checked to be inside the workspace; links are resolved through the part of the path that exists; a save directory that leads outside is refused when the image is saved. The code sample follows validatePathInsideWorkspace.
  • Input Validation: numeric values are clamped, a value of the wrong type falls back to the default, the save-directory and file-name-pattern checks are warnings, and file names are sanitized as above.
  • The comment in sanitizeConfiguration no longer claims a filter on fileName.pattern that the code does not apply.

Verification

  • npm run lint, npm run compile, the configuration tests.
  • Each statement checked against the source named above. The README's own Security and Privacy section already describes the workspace check as it is and is unchanged.

🤖 Generated with Claude Code

SECURITY.md said that the save directory cannot be absolute or contain
`..`, and that file name patterns cannot contain shell metacharacters. Both
are reported as configuration warnings, not refused. What keeps the saved
image inside the workspace is the check against the workspace's real path:
it refuses a save directory that leads outside, and lets one whose `..`
stays inside resolve to the folder it names. The sections now say so, the
code sample follows the check as it is written, and the file name
sanitizing is described as it is: control characters and the characters a
Windows file name cannot hold are removed, and on Windows a reserved name is
prefixed.

The comment in sanitizeConfiguration said fileName.pattern keeps only safe
characters, a filter the code does not apply; it now says what happens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kkdev92
kkdev92 merged commit a259130 into main Oct 3, 2026
16 checks passed
@kkdev92
kkdev92 deleted the docs/security-claims branch October 3, 2026 14:58
@kkdev92 kkdev92 mentioned this pull request Oct 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant