diff --git a/README.md b/README.md index ca50471..78a6ca6 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,117 @@ # 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` -- https://webextension-api.thunderbird.net/en/mv3/cloudFile.html +- **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 `/` 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 -- 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` +This repository intentionally stays conservative: -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. -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 `/` to Thunderbird. +## Architecture Overview -Configuration notes: +The add-on is small and centered around Thunderbird `cloudFile` event handlers: -- `baseUrl` should point at the PsiTransfer download/share root. -- `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`. -- The provider validates retention values and max file size against `config.json`. -- If the PsiTransfer server requires bucket passwords, the provider currently stops with an explicit error because bucket-password UI is not implemented yet. +- `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. -Building: +### Key Files -- Run `./build-xpi.sh` on Unix-like systems or `powershell ./build-xpi.ps1` on Windows. -- The scripts read the version from `manifest.json` and write `release/psitransfer-filelink-.xpi`. +| 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. | -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-.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 /config.json` + - validates retention, file size, and bucket-password requirements + - uploads the file through tus to `/files` + - locks the bucket with `PATCH /files/?lock=yes` + - returns the bucket share URL `/` + +### 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.