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.