117 lines
7 KiB
Markdown
117 lines
7 KiB
Markdown
# FileLink-PsiTransfer
|
||
|
||
PsiTransfer Filelink is a Thunderbird Manifest V3 `cloudFile` provider scaffold for
|
||
[PsiTransfer](https://github.com/psi-4ward/psitransfer). It currently targets a
|
||
minimal v1 integration: configure a PsiTransfer instance, upload one Thunderbird
|
||
attachment into one PsiTransfer bucket, lock the bucket, and return the bucket
|
||
share URL to Thunderbird.
|
||
|
||
The transport behavior in this repository is derived from the PsiTransfer source in
|
||
`/tmp/psitransfer` and the Thunderbird `cloudFile` API documentation. It does not
|
||
assume PsiTransfer exposes a polished public provider API beyond what its frontend
|
||
and server code actually implement.
|
||
|
||
## Features
|
||
|
||
- **Thunderbird MV3 Filelink provider** – registered through the manifest `cloud_file` entry and background event listeners.
|
||
- **Per-account configuration UI** – set the base PsiTransfer URL, optional upload app path, optional upload password, default retention, and optional custom SID.
|
||
- **Source-informed PsiTransfer upload flow** – probe `GET /config.json`, upload through the vendored tus client, then lock the bucket with `PATCH /files/:sid?lock=yes`.
|
||
- **Bucket share URL return** – returns the bucket URL `/<sid>` to Thunderbird rather than a raw tus upload URL.
|
||
- **Retention validation** – validates the configured retention against the values exposed by PsiTransfer `config.json`.
|
||
- **Max file size validation** – fails early when a file exceeds the PsiTransfer server's configured maximum upload size.
|
||
- **Abort handling** – supports Thunderbird upload abort requests for active tus uploads.
|
||
- **Stored upload metadata** – keeps per-account config and uploaded-file references in `storage.local`.
|
||
- **Packaging scripts** – `build-xpi.ps1` and `build-xpi.sh` build an installable XPI from the repository.
|
||
- **Vendored tus client** – uses the local `vendor/tus.js` bundle instead of loading `tus-js-client` from a CDN at runtime.
|
||
|
||
### Current Scope
|
||
|
||
This repository intentionally stays conservative:
|
||
|
||
- Upload is implemented.
|
||
- Bucket locking after upload is implemented.
|
||
- Thunderbird template hints for expiry and one-time downloads are implemented.
|
||
- Delete, rename, and upload reuse are intentionally not claimed as supported provider behavior.
|
||
|
||
## Architecture Overview
|
||
|
||
The add-on is small and centered around Thunderbird `cloudFile` event handlers:
|
||
|
||
- `src/background.js` boots the provider and registers the Thunderbird listeners.
|
||
- `src/cloudfile/provider.js` maps Thunderbird account and upload events onto PsiTransfer operations.
|
||
- `src/psitransfer/client.js` implements the PsiTransfer-facing config probe, tus upload, bucket lock, and share URL resolution.
|
||
- `src/cloudfile/account-store.js` persists account settings and uploaded-file records in `storage.local`.
|
||
- `ui/account.html`, `ui/account.js`, and `ui/account.css` provide the account management page opened from Thunderbird.
|
||
- `docs/psitransfer-notes.md` records the exact PsiTransfer files and behaviors used as the integration source of truth.
|
||
|
||
### Key Files
|
||
|
||
| Path | Purpose |
|
||
| --- | --- |
|
||
| `manifest.json` | Thunderbird MV3 manifest, permissions, icons, and `cloud_file` registration. |
|
||
| `src/background.js` | Provider bootstrap and Thunderbird event wiring. |
|
||
| `src/cloudfile/provider.js` | Account lifecycle handling, upload entry point, and Thunderbird return payloads. |
|
||
| `src/psitransfer/client.js` | PsiTransfer config probe, tus upload flow, bucket lock, and share URL logic. |
|
||
| `src/cloudfile/account-store.js` | `storage.local` persistence for account and uploaded-file records. |
|
||
| `ui/account.html` and `ui/account.js` | Account settings UI shown from Thunderbird's Filelink management page. |
|
||
| `docs/psitransfer-notes.md` | Confirmed PsiTransfer behavior, source references, and unresolved areas. |
|
||
| `vendor/tus.js` | Vendored `tus-js-client` browser bundle used by the background context. |
|
||
|
||
## Building
|
||
|
||
1. Ensure `zip` is available on Unix-like systems or PowerShell/.NET compression support is available on Windows.
|
||
2. Run `./build-xpi.sh` on Linux/macOS or `powershell ./build-xpi.ps1` on Windows.
|
||
3. The build script reads the version from `manifest.json` and writes `release/psitransfer-filelink-<version>.xpi`.
|
||
4. Install the generated XPI in Thunderbird through the Add-ons Manager, or load the repository as a temporary add-on during development.
|
||
|
||
## Usage
|
||
|
||
1. Add the PsiTransfer Filelink provider in Thunderbird.
|
||
2. Open the provider's management page and configure:
|
||
- `Base PsiTransfer URL`: the share/download root of the PsiTransfer instance, for example `https://files.example.com/`.
|
||
- `Upload app path`: optional override for the upload mount base. Leave it as `/` unless your PsiTransfer deployment mounts uploads under a subpath that `config.json` does not reveal.
|
||
- `Optional upload password`: sent as the `x-passwd` header when the server protects uploads.
|
||
- `Default retention / expiry`: a retention value accepted by the server, such as `604800` or `one-time`.
|
||
- `Custom SID behavior`: optional explicit bucket ID. Leave blank to let the provider generate one.
|
||
3. Save the settings. The provider marks the account configured once a base URL is present.
|
||
4. Attach a file in Thunderbird and choose PsiTransfer Filelink.
|
||
5. During upload, the provider:
|
||
- requests `GET <baseUrl>/config.json`
|
||
- validates retention, file size, and bucket-password requirements
|
||
- uploads the file through tus to `<uploadAppPath>/files`
|
||
- locks the bucket with `PATCH <uploadAppPath>/files/<sid>?lock=yes`
|
||
- returns the bucket share URL `<baseUrl>/<sid>`
|
||
|
||
### Notes
|
||
|
||
- `config.json` does not expose PsiTransfer's `uploadAppPath`, so non-default upload mounts must currently be configured manually.
|
||
- If the PsiTransfer server requires a bucket password, uploads fail with an explicit error because the Thunderbird UI does not expose bucket-password entry yet.
|
||
- The current implementation is bucket-oriented but Thunderbird `cloudFile` uploads are file-oriented, so each Thunderbird upload currently uses its own PsiTransfer bucket.
|
||
|
||
## Required Permissions
|
||
|
||
PsiTransfer Filelink currently requests these Thunderbird permissions:
|
||
|
||
- `cloudFile` – register the provider and handle Thunderbird Filelink upload lifecycle events.
|
||
- `storage` – persist account settings and uploaded-file references.
|
||
- `http://*/*` and `https://*/*` host permissions – contact the configured PsiTransfer instance.
|
||
|
||
## Thunderbird Add-on Store Disclosures
|
||
|
||
The [Third Party Library Usage](https://extensionworkshop.com/documentation/publish/third-party-library-usage/)
|
||
policy requires disclosure of bundled third-party libraries. This add-on currently
|
||
ships:
|
||
|
||
- [tus-js-client 4.3.1](https://github.com/tus/tus-js-client)
|
||
- Bundled locally as `vendor/tus.js`
|
||
- MIT License
|
||
|
||
## License
|
||
|
||
This project is licensed under the MIT License. See `LICENSE` for the full text.
|
||
|
||
## Implementation Notes
|
||
|
||
PsiTransfer-specific integration details, confirmed source references, and unresolved
|
||
questions are tracked in `docs/psitransfer-notes.md`. If upload behavior changes, that
|
||
document should be updated alongside the implementation.
|