wagesj45/FileLink-PsiTransfer
wagesj45/FileLink-PsiTransfer
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

Update README for current PsiTransfer provider

Browse source
This commit is contained in:
Jordan Wages 2026-04-20 12:00:46 -05:00
commit e04fe8fa30
1 changed files with 103 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

129
README.md
View file

@ -1,40 +1,117 @@
# FileLink-PsiTransfer # FileLink-PsiTransfer
Thunderbird Manifest V3 Filelink/cloudFile provider for 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.
Current status: minimal v1 upload path implemented. The extension now performs a source-informed tus upload, locks the PsiTransfer bucket, and returns the bucket share URL to Thunderbird. Delete, rename, and upload reuse remain intentionally unimplemented until the PsiTransfer source proves a stable provider-facing contract. 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.
The real integration contract must be derived from: ## Features
- `/tmp/psitransfer` - **Thunderbird MV3 Filelink provider** – registered through the manifest `cloud_file` entry and background event listeners.
- https://webextension-api.thunderbird.net/en/mv3/cloudFile.html - **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.
This repository already includes: ### Current Scope
- `manifest.json` for a Thunderbird MV3 `cloud_file` provider This repository intentionally stays conservative:
- background and provider scaffolding under `src/`
- a minimal account management UI under `ui/`
- a vendored local copy of `tus-js-client` at `vendor/tus.js`
- implementation notes in `docs/psitransfer-notes.md`
- agent workflow guidance in `AGENTS.md`
Current provider behavior: - 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.
1. Read `GET /config.json` from the configured base URL with the optional `x-passwd` header. ## Architecture Overview
2. Upload one Thunderbird attachment to one PsiTransfer bucket using the vendored tus client.
3. Lock the bucket with `PATCH /files/:sid?lock=yes`.
4. Return the bucket share URL `/<sid>` to Thunderbird.
Configuration notes: The add-on is small and centered around Thunderbird `cloudFile` event handlers:
- `baseUrl` should point at the PsiTransfer download/share root. - `src/background.js` boots the provider and registers the Thunderbird listeners.
- `uploadAppPath` is optional and defaults to `/`. Use it only when the server mounts uploads under a subpath relative to `baseUrl`, because `config.json` does not expose `uploadAppPath`. - `src/cloudfile/provider.js` maps Thunderbird account and upload events onto PsiTransfer operations.
- The provider validates retention values and max file size against `config.json`. - `src/psitransfer/client.js` implements the PsiTransfer-facing config probe, tus upload, bucket lock, and share URL resolution.
- If the PsiTransfer server requires bucket passwords, the provider currently stops with an explicit error because bucket-password UI is not implemented yet. - `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.
Building: ### Key Files
- Run `./build-xpi.sh` on Unix-like systems or `powershell ./build-xpi.ps1` on Windows. | Path | Purpose |
- The scripts read the version from `manifest.json` and write `release/psitransfer-filelink-<version>.xpi`. | --- | --- |
| `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. |
Do not assume PsiTransfer exposes a polished external API. This scaffold is intentionally conservative and keeps unresolved behavior as explicit TODOs. ## 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.