Add initial PsiTransfer Filelink provider scaffold

docs/psitransfer-notes.md

@@ -0,0 +1,124 @@
+# 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.