auth plugin

Writing a sign-in plugin

An authentication plugin signs an account in through the provider's own flow — a PIN, a device code, a confirmation page — without a password ever being typed into rDownloader. begin starts the flow and returns what the person has to do; poll asks the provider whether they have done it, and stores the key the provider hands over.

For a provider with OAuth tokens that expire and have to be renewed, write an OAuth sign-in instead.

Scaffold	rdownloader plugin new --type auth
plugin_type	auth
World	auth-plugin
Exports	begin, poll
Template	sdk/templates/auth
Contract	Interface auth

What the host promises

• You never see a stored credential. credential-ref is an opaque handle, and the key you obtain goes back through credentials.store-token. There is no call that reads one back.
• The account you are handed is the only one you can write to. Naming another is refused.
• You remember nothing between calls. Whatever poll needs from begin goes back in flow-state, which the host hands over verbatim on the next poll. That is what lets a sign-in survive a closed browser or a service restart.

Permissions

The scaffold asks for net_http with the provider's API and the site the person confirms on: a verification address outside that list is refused, and it is shown rather than opened. credentials is granted by the type and linked into no other world. An auth plugin may also ask for secrets and key_derivation, for a sign-in that leaves key material behind.

[extension] claims names the provider slug it signs in — one plugin, one provider.

Ask for exactly what you use: the install preview shows every grant, and a component importing an interface its manifest does not grant cannot be instantiated. Every capability is listed under Capabilities.

Rules worth knowing first

Store the key with credentials.store-token before answering authorized, and keep flow-state bookkeeping, never a credential. The waiting is the host's: answer pending(n) and the host asks again in n seconds.

Step by step

1. Scaffold it

plugin new reads its templates from sdk/templates, so run it from a checkout of the repository:

git clone https://github.com/degoya/rDownloader.git
cd rDownloader
rdownloader plugin new --type auth --out ../mysignin
cd ../mysignin

Without an installation of rDownloader, the packaging tool rd-pack — cargo build --profile release-test -p rd-pack in the checkout — takes the same arguments: target/release-test/rd-pack plugin new --type auth --out ../mysignin.

The directory name becomes the crate name and the plugin's slug (--name sets another). The scaffold gets its own plugin id, its own copy of the contract in wit/rdownloader.wit and its own Ed25519 key pair: plugin-signing.key, whose public half is already in manifest.toml. Keep that file out of version control.

2. Make it yours

• src/lib.rs reads the provider's answers and the flow state; the scaffold runs a PIN sign-in against a made-up API.
• src/guest.rs holds begin and poll.
• manifest.toml: [capabilities.net_http] domains, [extension] claims.
• locales/en.json: the English text of every failure code you report.

Change description and author under [metadata], and read the comment at the top of src/lib.rs: it states what the host promises this type.

3. Test it

cargo test

The unit tests need no WebAssembly toolchain: only src/guest.rs is wasm32-specific. Give every answer of your provider you read a test of its own.

4. Build the component

cargo build --release --target wasm32-unknown-unknown
wasm-tools component new target/wasm32-unknown-unknown/release/mysignin.wasm -o target/mysignin.wasm

This needs the wasm32-unknown-unknown target and wasm-tools 1.261.0, the version the bundled plugins are made with: cargo build makes a core module that carries the world src/guest.rs generates, and wasm-tools component new turns it into the component. The plugin is built without WASI: a component importing anything outside rdownloader:plugin is refused — see Building without WASI.

5. Package and sign it

rdownloader plugin package --manifest manifest.toml \
  --component target/mysignin.wasm \
  --locales locales --key plugin-signing.key --output mysignin.rdplug
rdownloader plugin conformance mysignin.rdplug --json

conformance answers whether this application would run the package; it has to be clean before you publish. For a key that outlives the scaffold, rdownloader plugin keygen --role plugin --output ./keys writes a pair: the Base64 in the .pub file goes into public_key, and key_id gets a name of your own. In CI, RDOWNLOADER_PLUGIN_SIGNING_KEY holding the private key's PEM text replaces --key. Details: Packaging, signing and distribution.

6. Install and trust it

For a first try without signing, package with --development instead of --key and start rdownloader serve --plugin-development-mode, the only mode that accepts an unsigned package.

Install a signed package under Settings → Plugins → Add as an upload, or with rdownloader plugin install mysignin.rdplug --root data/plugins. Review before installing shows every permission and the signing key; a key this installation has not seen asks to be trusted — compare its fingerprint. The message after installing says whether the plugin runs at once or after the next restart; see Installing and trust.

The account form of the provider named in claims, under Settings → Accounts, offers the sign-in.

7. Publish it

Publish the .rdplug together with your key's fingerprint, or — so that people get your new versions in the Catalogue — in a plugin repository of your own: a signed index built with rdownloader plugin index build and a repository-role key. A repository only delivers: every package in it still needs your plugin key, approved by the person installing it. See A repository index and Running a plugin repository.

The SDK's reusable CI workflow, sdk/ci/plugin.yml, builds, checks the imports, packages and runs conformance on every push and pull request; it signs only on a push to the default branch or a tag, so a pull request never sees the key.

Read next

• Authentication providers in the plugin reference — what the host does with each call, in full
• Interface auth — every function and type, generated from the contract
• Developing a plugin — the tools, translations, errors and what every type shares
• The auth template on GitHub