# Package and distribute a plugin

A plugin installation is a signed `.etplugin` archive containing a manifest,
target-specific libraries, declared dependencies, assets and license notices.
The host verifies the publisher and every inventoried file before loading code.
External redistribution terms for this SDK remain [pending](../REDISTRIBUTION.md).

## Development and distribution

Development mode accepts an explicitly named unsigned manifest for one launch.
It is useful for iteration. Installation uses the signed package manifest
described in [the package contract](PACKAGE.md). Do not put a development
manifest directly into an archive and expect production installation to accept it.

## Prepare the payload

```text
payload-root/
  payload/windows-x64/my-plugin.dll
  assets/icon.png
  licenses/your-plugin.txt
```

Declare the matching target entry in your package manifest. Include only needed
files. Native dependencies belong under their target payload directory and must
be declared in `dependencies`. Images use package-relative `assets/...` paths.
Application source, captured ECU data, private keys and customer tunes never
belong in the payload.

Use the generated
[licensed example manifest](../examples/licensed-feature-demo/package-manifest.json.in)
or [ImGui manifest](../examples/imgui-inspector/package-manifest.json.in) as a
schema example. Replace the test publisher and placeholder product URLs, set
your host/ABI requirements and select the exact capabilities used by your binary.
The `files` inventory is populated by the packaging tool.

## Sign

```sh
python -m pip install -r tools/requirements.txt
python tools/package.py --manifest package-manifest.json --payload-root payload-root --key /outside/sdk/publisher.pem --output my-plugin.etplugin
```

Supply an external Ed25519 private PEM. The tool does not create or embed private
keys. It refuses an existing output path. Keep the resulting package immutable;
build a new semantic version for an update. Full canonicalization, inventory
and signature rules are in [PACKAGE.md](PACKAGE.md).

## Verify and install

Prepare a publisher public-key file with `publisher`, `keyId`, `publicKey`
(32-byte hexadecimal Ed25519 public key). The imported file has exactly these three keys; the host adds revocation state to its trust registry. Review the
identity before importing it through **Tools → Plugins → Trust publisher key**.
Choose **Install package**, select the archive, review requested capabilities
and enable it. The host verifies native OS/architecture and required features.

For automation, the separate package checker takes the archive and a trust
registry containing `{"schema":1,"keys":[...]}`:

```sh
epictuner-plugin-package-check my-plugin.etplugin trust.json
```

That checker verifies the package; it does not install it or exercise the UI.
Run the actual application acceptance case after installation.

## Updates and recovery

An update stops the worker, stages and verifies an immutable version, then
switches the active registry. New capabilities require review. Failed updated
workers trigger rollback; plugin settings snapshots are handled separately.
Test schema migration and rollback before delivery.

Use `--safe-mode` if a plugin prevents normal startup. It suppresses third-party
starts while retaining management/recovery access. Do not repair a package by
editing its installed files; that invalidates its signature/inventory.

## Paid features and catalogs

Publisher trust authenticates the binary. Issuer trust authenticates an
entitlement. They are separate identities and checks. Follow
[licensing](LICENSE.md) for a local test issuer and offline activation.

The SDK's `tools/test-catalog.py` creates a signed local catalog for developer
acceptance. Its domain-separated signature authenticates canonical catalog content
and package hashes against an explicitly supplied public key. Production hosting,
catalog discovery, issuer operations, purchase/refund and publisher payouts
are outside this test catalog and remain later commercial-service work.