Getting started

ArcaPhylax is built from source for now. You need the .NET 11 SDK.

git clone https://github.com/FreeApophis/ArcaPhylax.git
cd ArcaPhylax
dotnet run --project ArcaPhylax/ArcaPhylax.csproj

The build also publishes the bundled plugins next to the app. Your library lives in a SQLite database in your user profile; nothing leaves your computer.

Installing plugins

Open the Plugins page (bottom of the navigation bar):

  • Available online lists the plugins from the catalog with the version for your computer. Install downloads, checks and loads a plugin right away; its pages appear in the navigation bar.
  • Update appears when a newer version is published. Updates and removals take effect when ArcaPhylax restarts, because a running plugin's files cannot be replaced.
  • Install from file… installs a downloaded .arcaplugin package.

Installed plugins live in %LOCALAPPDATA%\ArcaPhylax\plugins on Windows (~/.local/share/ArcaPhylax/plugins on Linux). An installed plugin replaces the bundled copy of the same plugin.

What ArcaPhylax checks

  1. The download has exactly the size and SHA-256 the catalog lists.
  2. Every file in the package matches its signature.
  3. The signer is a trusted publisher, and owns the plugin's id (see below).
  4. The package is for this platform (for example win-x64) and this plugin SDK: same major version, minor version no newer than the app's.

Trusted publishers

Plugins run inside ArcaPhylax with the same access to your computer as the app itself, so ArcaPhylax only installs plugins from publishers someone vouched for:

  • Endorsed publishers are listed in publishers.json, which is signed with the ArcaPhylax root key. Each publisher owns plugin id prefixes: a publisher endorsed for Contoso may publish Contoso and Contoso.*, and nobody else may.
  • Revoked keys are listed there too. Plugins signed with a revoked key stop loading at the next start.
  • You decide on your computer: you can trust a publisher that is not endorsed (for example your own key while developing a plugin), or block an endorsed one. A key you trust cannot publish plugins under an id an endorsed publisher owns, and a revocation cannot be overridden.

Writing a plugin

A plugin is a .NET class library that references ArcaPhylax.Plugin.Sdk and nothing else from ArcaPhylax. It runs in its own load context; Avalonia, Autofac, CommunityToolkit.Mvvm and the SDK come from the app, everything else ships with the plugin.

Start from the template

You need the .NET 11 SDK. Install the template and the pack tool once, then create a plugin:

dotnet new install ArcaPhylax.Plugin.Templates
dotnet tool install --global ArcaPhylax.PluginPack

dotnet new arcaphylax-plugin -n Contoso.Hello --title "Hello" --plugin-author "Contoso"

The project builds as it is: one page with a view model, an Avalonia view and an Autofac module. Use a name made of dot-separated letters and digits; it becomes the plugin id.

Project

A plugin references the ArcaPhylax.Plugin.Sdk package and describes itself in the project file:

<PropertyGroup>
  <PluginId>Contoso.Hello</PluginId>
  <Title>Hello</Title>
  <Description>Says hello.</Description>
  <Authors>Contoso</Authors>
  <Version>1.0.0</Version>
  <!-- Optional: <PluginPlatforms>win-x64;win-arm64</PluginPlatforms> -->
</PropertyGroup>

<ItemGroup>
  <PackageReference Include="ArcaPhylax.Plugin.Sdk" Version="1.0.0" />
</ItemGroup>

The SDK package brings the Avalonia, Autofac and CommunityToolkit.Mvvm versions ArcaPhylax provides, and build rules that leave them out of your published output: the app supplies them at runtime.

Entry point

Implement IPlugin once and register your services in an Autofac module:

internal sealed class HelloPlugin : IPlugin
{
    public void Configure(ContainerBuilder builder) => builder.RegisterModule<HelloModule>();

    public Task StartAsync(CancellationToken cancellationToken) => Task.CompletedTask;

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

internal sealed class HelloModule : Module
{
    protected override void Load(ContainerBuilder builder)
    {
        builder.RegisterType<HelloViewModel>().As<ITabContentViewModel>().AsSelf().SingleInstance();
        builder.RegisterType<HelloView>();
    }
}

Every ITabContentViewModel becomes a page in the navigation bar. Its view is found by name: Hello.ViewModels.HelloViewModel → Hello.Views.HelloView, in the same assembly. IConfigurationSection registrations add a section to the Configure page.

Types that cross between plugin and app must come from the SDK. Plugins get the app's repositories through their interfaces in ArcaPhylax.Abstractions.

Every other library your plugin uses ships inside your package, in your plugin's own copy. One exception: assemblies whose name starts with Avalonia always come from the app, so only use Avalonia packages that ArcaPhylax itself ships.

Packaging and signing

A plugin is distributed as one .arcaplugin file per platform: a zip with plugin.json, the published files under payload/, and signature.json (ECDSA P-256 over the SHA-256 of every entry).

The arcaphylax-pluginpack tool (dotnet tool install --global ArcaPhylax.PluginPack) does all of it. Create a signing key once and keep it out of your repository:

arcaphylax-pluginpack keygen ~/arcaphylax-plugins.key

It prints the public key. To get your plugins listed, ask for that key to be endorsed (see Publish your plugin); for testing on your own computer, trust it when you install.

Pack, sign and verify a plugin:

arcaphylax-pluginpack pack Contoso.Hello/Contoso.Hello.csproj \
    --key ~/arcaphylax-plugins.key --rid win-x64 --out artifacts/plugins
OptionMeaning
--keyPrivate key file. Defaults to the ARCAPHYLAX_PLUGIN_KEY environment variable.
--ridPlatform to publish for. Defaults to this machine.
--outOutput folder. Defaults to artifacts/plugins.
--catalogAlso add the package to this catalog.json (created if missing).
--base-urlWith --catalog: link the package as <url>/<file>, e.g. a release download URL.

Publishing

This website and the plugin catalog are built by .github/workflows/pages.yml on every push to main. It packs every plugin under Plugins/ for each platform in its PluginPlatforms (skipping plugins with <PluginInCatalog>false</PluginInCatalog>), writes catalog.json and deploys the site to GitHub Pages.

The signing key comes from the repository secret PLUGIN_SIGNING_KEY (the PEM file's contents). To release a new version, raise <Version> in the plugin's project file and push.

To try a catalog before publishing it, point the app at a local file:

arcaphylax-pluginpack pack Plugins/Hello/Hello.csproj --out site-test/plugins --catalog site-test/catalog.json
ARCAPHYLAX_PLUGIN_CATALOG=site-test/catalog.json dotnet run --project ArcaPhylax/ArcaPhylax.csproj

Publish your plugin

Anyone can write a plugin. To have it listed in the catalog (and offered on the Plugins page in ArcaPhylax), you host the packages yourself and ArcaPhylax lists them:

  1. Create your signing key and keep the private key file to yourself:
    arcaphylax-pluginpack keygen my.key
  2. Get endorsed. Open a publisher endorsement issue with your public key and the plugin id prefix you want (for example Contoso, which covers Contoso and Contoso.*). Once endorsed, your key is in publishers.json.
  3. Pack for each platform and upload the .arcaplugin files to a release, for example on GitHub. With --catalog and --base-url, the pack tool writes your listing file:
    arcaphylax-pluginpack pack Hello/Hello.csproj --key my.key --rid win-x64 \
        --out out --catalog catalog/contoso.json \
        --base-url https://github.com/contoso/hello/releases/download/v1.0.0
  4. Open a pull request adding catalog/contoso.json to the ArcaPhylax repository. A check downloads every listed package and verifies its size, hash, signature, contents and publisher before it can be merged.

While you develop, you do not need an endorsement: install your package with Install from file… and choose Trust and install for your own key. That trust applies to your computer only.

Never replace a released package file: users' downloads are checked against the listed SHA-256. Publish a new version instead.

Catalog format

catalog.json lists every plugin with all published packages. Package URLs are relative to the catalog.

{
  "schemaVersion": 1,
  "plugins": [
    {
      "id": "ArcaPhylax.Nutrition",
      "name": "Nutrition",
      "description": "Track daily calories and body weight per person, with charts of your progress.",
      "author": "Apophis",
      "entryAssembly": "NutritionPlugin.dll",
      "packages": [
        {
          "version": "1.0.0",
          "platform": "win-x64",
          "sdkVersion": "1.0.0",
          "url": "plugins/ArcaPhylax.Nutrition-1.0.0-win-x64.arcaplugin",
          "size": 1650000,
          "sha256": "…"
        }
      ]
    }
  ]
}

The catalog only says what exists and where. Trust comes from each package's signature, so a changed catalog cannot make ArcaPhylax install an unsigned or foreign package.