Oruva
Plugin API v1 · Distribution

Plugin Center & catalog

The Plugin Center joins public discovery with local plugin management. Users never see a raw permission id, a hash, or a signature: they see what a plugin can do, one button per card, and one approval sheet.

The Plugin Center has three tabs — Discover, Installed, Develop — behind one header with the Oruva mark. Opening it lands on Discover when a store or bundled listing is available and on Installed otherwise. The footer shows where local plugins live, a Plugins folder button, a Developer docs link, and Refresh. The Installed tab carries a count badge; Discover carries a badge when updates are waiting.

Discover

  • A search field and category chips narrow the listings; an Updates chip appears only when an installed plugin has a newer version. The status pill reads Store online, Included with Oruva (bundled listings only), or Showing the last loaded store (cached catalog).
  • Every card shows the plugin's real icon — the installed copy's icon, the bundled example's icon, or the store listing's icon_url proxied through the backend — falling back to initials only when a listing declares none. Cards carry the name, author, version, description, category chips, and short "needs" chips in plain words (Reads assets, Writes files, Internet, Opens browser, Library path, Reads files) derived from the manifest permissions. Raw permission ids never appear in the Plugin Center.
  • Each card has exactly one primary button for its state: Install for a card that is not installed, Update to vX when a newer bundled or signed store version exists, Turn on when it is installed but off, Allow when its files changed, and an On pill when it is running. A Manage link jumps to the matching row under Installed; Details opens the listing on oruva.app when one exists.
  • Installing does not enable anything. It copies or downloads the plugin and then opens the approval sheet in place, so one Install and one Allow and turn on is the whole flow. Dismissing the sheet leaves the plugin installed and off.
  • Bundled plugins. The five example plugins that ship with the app (oruva.asset-dossier, oruva.sky-match, oruva.example.asset-report, oruva.pinterest-search, oruva.search-by-image) appear as Included with Oruva and install from the local copy — no download. Each is pinned by version and content SHA-256 in the app; a bundled copy that fails that integrity check is refused. The bundled listing is what users see for these ids; a signed store row for the same id only adds an update lane when it is strictly newer and downloadable.
  • Store listings. The catalog at https://plugins.oruva.app/v1/catalog.json is fetched by the backend (HTTPS, six-second timeout, 2 MiB limit, every field validated, last valid copy cached). Listings carry name, version, author, description, categories, media types, permissions, compatibility, an optional icon_url on an oruva.app host, and optional package metadata. Icons are downloaded by the backend as well — HTTPS only, official host, no redirects, 512 KiB cap, raster or SVG only — and cached for a day.

Signed catalog and verified installs

  • The catalog document is Ed25519-signed, and each installable row carries its own Ed25519 package_signature over id, version, package_sha256, and package_size. Verification keys ship with the app in plugin_sdk/trusted_publishers.json; signing keys never leave Oruva.
  • A store install verifies the catalog signature, the package signature, and the package SHA-256, downloads at most 64 MiB from an oruva.app host without redirects, rejects unsafe or duplicate archive paths and symlinks, limits extracted data to 256 MiB, validates the manifest, checks that the manifest id matches the catalog id, and atomically moves the plugin into place. The installed plugin lands switched off and unapproved; the approval sheet is the only route to execution.
  • Packaged builds fail closed: without a trusted key, or when either signature does not verify, the install is refused with plugin_signing_required. The shipped trust store is empty until Oruva publishes its first audited key, so today only bundled plugins install from Discover in production builds. Unsigned installs exist solely behind a non-packaged developer override.
  • Once a valid signed catalog has been cached, an older generated_at timestamp or a lower version for any known plugin is refused, so a replayed catalog cannot downgrade users.

Updates

  • Discover compares every bundled or store version with the installed one using full SemVer precedence, prereleases included. A newer version shows an Update to vX button and counts toward the Updates chip and the Discover tab badge.
  • Pressing it swaps the installed folder atomically: the new copy is staged and verified first (bundled copies against their content pin, store packages against both signatures and the SHA-256), the old folder is moved aside, the new one takes its place, and the old one is deleted only after that succeeds. If anything fails the previous copy is restored untouched. The local API exposes the same operation as POST /api/plugins/bundled/update and POST /api/plugins/update with {"id": "..."}.
  • An update keeps the plugin's on/off switch position but drops its approval and every internet grant, because the content hash changed. The approval sheet opens right after the swap, so users see exactly what the new version can do before it runs again.
  • Linked development plugins never update from Discover — their folder is the source of truth — and a version that is not newer than the installed one is refused with plugin_up_to_date.

Installed

  • Each row shows the icon, name, version chip, an optional Linked folder chip, a plain-language status line (On · 1 action in the right-click menu, Off · Switch it on to add it to the right-click menu, Needs your OK again · Its files changed since you last allowed it, Not compatible, Invalid), the description, and chips for the author and its needs.
  • The On/Off switch is the approval gate. Switching a plugin on opens a single approval sheet: what it can do (each permission in plain words, write scopes spelled out, every internet destination with its purpose and the data it sends), what it adds to the right-click menu, and a collapsed Trust before execution note with the entry path — then Allow and turn on. Switching off disables it immediately. A plugin whose files changed shows Needs your OK again and the sheet's button reads Allow again.
  • A row menu holds the rest: Open folder, Pack .oruvaplugin, Reset internet access (shown when the plugin declares network destinations; it returns every origin to ask), and Remove (local plugins go to the operating system's Recycle Bin) or Unlink (linked development plugins are forgotten without touching their files).

Develop

  • Two cards start a project: Create a plugin opens the Create dialog (name, optional icon, template, advanced options) and Link an existing folder links a project in place.
  • A three-step Developer workflow strip (create or link → edit and test → validate and package) sits above SDK guide, Examples, and Online docs, with quick links into this documentation.
  • Linked development plugins lists every linked folder as a row with its path, its switch, and the same row menu (Open folder, Pack .oruvaplugin, Unlink).