feat(sftp): add option for absolute & parent symlink backups

[nicotsx]

Related issue: #1007

Recent SSHFS now contains absolute/parent-directory symlinks by default, which is safer for browsing but prevents Restic from archiving the original symlink metadata. This adds an opt-in no_contain_symlinks switch for trusted SFTP sources that need exact symlink backup

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1c8f0bf9-2514-4798-b60b-413d84bf5d66

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dosubot]

📄 Knowledge review

✏️ Documentation updates

1 page was updated by changes in this PR.

Page	Library	Status
Zerobyte Volumes: Types, Architecture, and Mounting	Zerobyte's Space	✅ Updated

📝 Zerobyte Volumes: Types, Architecture, and Mounting — changes

@@ -42,9 +42,10 @@
 ### 6. SFTP (SSH File Transfer Protocol)
 - [Secure file access over SSH](https://github.com/nicotsx/zerobyte/blob/bad944a2329540088a51f7699d6f53d9ac82137c/app/schemas/volumes.ts#L60-L71)
 - Supports both password and private key authentication
-- Configuration: host, port, username, password (optional), privateKey (optional), path, readOnly flag, skipHostKeyCheck (optional), knownHosts (optional), allowLegacySshRsa (optional)
+- Configuration: host, port, username, password (optional), privateKey (optional), path, readOnly flag, skipHostKeyCheck (optional), knownHosts (optional), allowLegacySshRsa (optional), allowUnsafeSymlinkTargets (optional)
 - SSH keys stored in an ephemeral temporary directory to avoid permission issues with certain bind mount configurations
 - `allowLegacySshRsa` enables legacy SSH RSA/SHA1 algorithms for compatibility with older SFTP servers that only offer ssh-rsa host key algorithms (weaker than modern SSH algorithms, should only be enabled for legacy servers)
+- `allowUnsafeSymlinkTargets` preserves absolute and parent-directory symlinks in their original form for backup instead of containing them (requires host key verification - knownHosts must be set and skipHostKeyCheck must be false, default: false)
 
 ## Volume Architecture
 
@@ -125,6 +126,7 @@
 - Support for both [password and private key authentication](https://github.com/nicotsx/zerobyte/blob/bad944a2329540088a51f7699d6f53d9ac82137c/app/server/modules/backends/sftp/sftp-backend.ts#L80-L89)
 - SSH keys stored in a system-managed temporary directory (rather than a persistent path) to improve compatibility with bind mount setups that don't properly support chmod operations
 - Optional `allowLegacySshRsa` flag to enable legacy SSH RSA/SHA1 algorithms (HostKeyAlgorithms=+ssh-rsa and PubkeyAcceptedAlgorithms=+ssh-rsa) for compatibility with older SFTP servers
+- Optional `allowUnsafeSymlinkTargets` flag to preserve absolute and parent-directory symlinks in their original form. Recent SSHFS versions contain absolute/parent-directory symlinks by default for safer browsing, but this prevents Restic from archiving original symlink metadata. This opt-in option passes the `no_contain_symlinks` flag to SSHFS for trusted SFTP sources that need exact symlink backup. For security reasons, this option requires host key verification and cannot be used with `skipHostKeyCheck` or when `knownHosts` is not configured
 - Reconnection settings for reliability
 
 ### Operation Timeouts
@@ -243,11 +245,14 @@
   "path": "/data",
   "skipHostKeyCheck": true,
   "allowLegacySshRsa": false,
+  "allowUnsafeSymlinkTargets": false,
   "readOnly": false
 }
 ```
 
 **Note**: The `allowLegacySshRsa` field defaults to `false` if omitted. When set to `true`, it enables legacy SSH RSA/SHA1 algorithms (ssh-rsa) for compatibility with older SFTP servers. This option is weaker than modern SSH algorithms and should only be enabled for legacy servers that require it.
+
+The `allowUnsafeSymlinkTargets` field defaults to `false` if omitted. When set to `true`, it preserves absolute and parent-directory symlinks in their original form for backup instead of containing them. This requires host key verification (knownHosts must be set and skipHostKeyCheck must be false). Only enable this for trusted SFTP servers that need exact symlink backup.
 
 ## Docker Setup Requirements
 

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70da7941a7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".