FileLink-PsiTransfer/docs/psitransfer-notes.md

PsiTransfer Notes

This document records the PsiTransfer behavior inferred from the local source at /tmp/psitransfer. It is intentionally narrow and only covers what was needed for the Thunderbird Filelink provider minimal v1 upload path.

Confirmed upload flow

1. PsiTransfer exposes upload-related frontend config from GET /config.json. Source: /tmp/psitransfer/lib/endpoints.js:133-158

2. PsiTransfer protects both GET /config.json and the upload mount with the x-passwd header when uploadPass is configured. Source: /tmp/psitransfer/lib/endpoints.js:134-142 /tmp/psitransfer/lib/endpoints.js:420-428

3. The upload mount is ${config.uploadAppPath}files. Source: /tmp/psitransfer/lib/endpoints.js:418-419

4. PsiTransfer uses tus semantics for upload creation and patching. Source: /tmp/psitransfer/lib/endpoints.js:479-552 /tmp/psitransfer/lib/tusboy/handlers/post.js /tmp/psitransfer/lib/tusboy/handlers/patch.js

5. On upload creation, PsiTransfer expects Upload-Metadata to include at least:

   • name
   • sid
   • retention Optional metadata observed in the frontend or server path:
   • password
   • comment
   • type Source: /tmp/psitransfer/lib/endpoints.js:480-531 /tmp/psitransfer/app/src/Upload/store/upload.js:133-151

6. PsiTransfer generates a random per-file key server-side and uses sid++key as the upload identifier. Source: /tmp/psitransfer/lib/endpoints.js:506-531

7. After all uploads in a bucket complete, the PsiTransfer frontend issues PATCH /files/:sid?lock=yes. Source: /tmp/psitransfer/app/src/Upload/store/upload.js:242-245 /tmp/psitransfer/lib/endpoints.js:440-446

8. The user-facing share URL is the bucket URL /<sid>, not the raw file URL under /files/.... Source: /tmp/psitransfer/app/src/Upload/store/upload.js:42-44 /tmp/psitransfer/lib/endpoints.js:199-246

9. The PsiTransfer frontend remembers the Location header from the tus POST response and then reuses that upload URL for the file PATCHes. Source: /tmp/psitransfer/app/src/Upload/store/upload.js:145-167 /tmp/psitransfer/lib/tusboy/handlers/post.js:1-73

10. PsiTransfer stores the upload resource at /files/<sid>++<key> and responds to tus POST with a relative Location header under the upload mount. Source: /tmp/psitransfer/lib/tusboy/handlers/post.js:49-73 /tmp/psitransfer/lib/endpoints.js:506-531

Confirmed configuration semantics

• Default configuration uses baseUrl: "/" and uploadAppPath: "/", then normalizes uploadAppPath relative to baseUrl. Source: /tmp/psitransfer/config.js:9-14 /tmp/psitransfer/config.js:36-46 /tmp/psitransfer/config.js:86-89

• config.json does not include uploadAppPath, so a client cannot discover a non-default upload subpath from that endpoint alone. Source: /tmp/psitransfer/lib/endpoints.js:145-155 /tmp/psitransfer/config.js:11-13 /tmp/psitransfer/config.js:86-89

• Default retention is "604800" and supported retention values come from config.retentions. Source: /tmp/psitransfer/config.js:25-34 /tmp/psitransfer/config.js:39-42 /tmp/psitransfer/lib/endpoints.js:148-155 /tmp/psitransfer/lib/endpoints.js:488-490

• The PsiTransfer frontend supports an explicit bucket id through the sid query parameter. Source: /tmp/psitransfer/README.md:28 /tmp/psitransfer/app/src/Upload/store/upload.js:20-30

Confirmed download/share hints relevant to Thunderbird

• Bucket JSON is available at /<sid>.json and includes per-item URLs under /files/<sid>++<key>. Source: /tmp/psitransfer/lib/endpoints.js:199-238

• Password-protected buckets are a real server-side concern; Thunderbird template hints can likely use download_password_protected. Source: /tmp/psitransfer/lib/endpoints.js:212-225

• One-time retention is implemented server-side and can map to Thunderbird download_limit: 1. Source: /tmp/psitransfer/config.js:25-34 /tmp/psitransfer/lib/endpoints.js:294-300 /tmp/psitransfer/lib/endpoints.js:392-395

Not yet established

• A stable public delete endpoint for previously uploaded files suitable for Thunderbird onFileDeleted.
• A stable public rename endpoint suitable for Thunderbird onFileRename.
• Whether the Thunderbird provider should upload one file per bucket or group related files into a shared bucket. PsiTransfer is bucket-oriented, while Thunderbird cloudFile uploads are file-oriented.
• Whether Thunderbird MV3 background service workers expose every browser primitive expected by the vendored tus-js-client bundle in all supported Thunderbird versions. The current implementation assumes the vendored bundle runs in the background worker.

Implemented minimal-v1 mapping

• Thunderbird configuration drives baseUrl, uploadAppPath, defaultRetention, and the optional upload password header.
• The provider probes GET <baseUrl>/config.json before upload to validate retention, max file size, and bucket-password requirements.
• The provider uses the vendored vendor/tus.js bundle for the tus POST and PATCH flow.
• After the tus upload completes, the provider sends PATCH <uploadAppPath>/files/<sid>?lock=yes.
• The provider returns the bucket share URL <baseUrl>/<sid> and Thunderbird templateInfo hints for retention and one-time downloads.

Implementation guidance

• Treat tus behavior as standard transport behavior, not a PsiTransfer-specific API by itself.
• Treat the bucket lock PATCH ...?lock=yes as PsiTransfer-specific behavior.
• Treat Thunderbird cloudFile event handling and return objects as a separate concern from the PsiTransfer transport.
• Prefer a minimal first implementation: configure endpoint, upload a single file, return the bucket share URL, and stop there until delete or rename support is proven.