FileLink-PsiTransfer

PsiTransfer Filelink is a Thunderbird Manifest V3 cloudFile provider scaffold for 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 policy requires disclosure of bundled third-party libraries. This add-on currently ships:

• tus-js-client 4.3.1
  • 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.