mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-16 20:11:08 +00:00
107 lines
5.9 KiB
Markdown
107 lines
5.9 KiB
Markdown
# Curated plugin catalog
|
|
|
|
The catalog lives in `electron/plugins/catalog.json` in this repository. There
|
|
is no new marketplace account service or external directory repository. It is
|
|
shipped with the app; catalog changes become available with an app update.
|
|
Normal Settings exposes browser-only management and catalog browsing. Advanced
|
|
local packages require `NETCATTY_PLUGIN_DEV=1`; that flag never grants permissions.
|
|
Native acceptance and security/distribution review remain required before merge.
|
|
|
|
## Submit or update a plugin
|
|
|
|
Open a PR changing one entry. Provide:
|
|
|
|
- Stable reverse-domain plugin ID, author, name and short description.
|
|
- Public GitHub source repository and explicit license matching the package.
|
|
- Exact version, full 40-character source commit and relative README `.md` path.
|
|
- The complete validated manifest: engine/API ranges, required/optional permissions,
|
|
bounded resources, features and data/sync declarations must match package bytes.
|
|
- Optional published artifact URL and SHA-256. No artifact means a source-only
|
|
example: the UI does not offer installation. Do not invent an artifact URL.
|
|
- A concise change log, permission diff, supported OS test results, and synthetic
|
|
reproduction instructions. Current public runtime eligibility is browser-only
|
|
on the host platforms; native/platform-specific companions are excluded.
|
|
|
|
Use the local CLI from the repository root:
|
|
|
|
```sh
|
|
npm ci
|
|
npm run build:plugin-packages
|
|
node packages/plugin-cli/dist/cli.js validate examples/plugins/hello-netcatty
|
|
node packages/plugin-cli/dist/cli.js pack examples/plugins/hello-netcatty --out /tmp/hello-netcatty.ncpkg
|
|
node packages/plugin-cli/dist/cli.js validate /tmp/hello-netcatty.ncpkg
|
|
```
|
|
|
|
The catalog contains first-party source examples: Plugin Starter for minimal
|
|
settings/command use, and Hello Netcatty for terminal provider demonstrations.
|
|
No downloadable release is fabricated or published by this change. A maintainer
|
|
must verify real artifact provenance before adding the artifact object.
|
|
|
|
## Enforced install boundary
|
|
|
|
The renderer sends only a catalog ID. The main process selects the shipped
|
|
entry, downloads over HTTPS from approved GitHub hosts with bounded size/time
|
|
and redirects, checks SHA-256, and hands a private file to the same serialized
|
|
PluginManager and PackageStore used for local imports. The immutable staged
|
|
snapshot is hashed again before any version switch. Its exact ID/version,
|
|
license and full manifest must match the catalog. Unknown permissions fail
|
|
canonical schema validation. Browser-only eligibility rejects Node entrypoints,
|
|
companions, raw terminal interceptors and advanced runtime declarations.
|
|
|
|
The directory is a curated integrity assertion, not a publisher signature.
|
|
Unsigned runtime grants remain bound to package digest. No latest fallback and
|
|
no background code updates exist. Installing an update stops the old version;
|
|
the new version remains disabled until reviewed and explicitly enabled. Required
|
|
permissions are mediated again by the existing runtime permission engine.
|
|
Local advanced development packages require the developer flag and use the existing permission model;
|
|
this does not grant advanced privileges or make Node a sandbox.
|
|
|
|
README is fetched only from the selected commit, on opening details. Redirects
|
|
are refused and responses are limited to 256 KiB. Rendering constructs a small
|
|
allowlist of React elements from Markdown; HTML remains escaped text and images
|
|
are not fetched. Only explicit HTTPS links can be opened. README content is
|
|
untrusted author documentation; permissions come from the manifest.
|
|
|
|
## Review and maintenance
|
|
|
|
CI now runs canonical plugin contract drift checks and the runtime suite,
|
|
including catalog validation and install-boundary regression tests.
|
|
Run `node --test electron/plugins/catalogService.test.cjs` and the plugin
|
|
contract/runtime tests for every entry change. Review actual package/source
|
|
provenance and permission/resource differences manually on first submission and
|
|
sensitive updates. Packaging validation includes traversal/integrity checks but
|
|
is not a malware audit. Human review is mandatory before adding an artifact;
|
|
there is no automated acceptance bot in this slice.
|
|
|
|
Authors maintain their plugins, document data handling and respond to security
|
|
reports. Maintainers may remove entries or decline updates. Directory checks
|
|
are limited checks, not a safety certification, legal waiver or a promise to
|
|
repair third-party plugins. No third-party terms are copied here.
|
|
|
|
## Data and lifecycle
|
|
|
|
Local KV is per-plugin and does not sync. Only explicitly syncable non-secret
|
|
settings enter encrypted sidecars; machine paths, grants, packages, runtime
|
|
state and secrets do not become cloud authority. Existing sidecar conflict and
|
|
account isolation mechanisms are reused. A generic KV sync API remains a separate
|
|
schema/migration decision.
|
|
|
|
Incompatible host/API/features disable plugins before lazy contributions are
|
|
published, retain package/data and record a reason. A compatible downgrade never
|
|
automatically re-enables them. Disable stops runtime and contributions; uninstall
|
|
removes package code and local KV, while user-owned settings/secrets/sidecars
|
|
remain. Existing crash quarantine and generation-bound cancellation apply.
|
|
|
|
Missing OS-backed key storage blocks secrets/credentials, without blocking
|
|
catalog browsing or non-secret plugins. The Settings manager reports this state;
|
|
never switch to plaintext storage or disable Chromium sandboxing for a demo.
|
|
|
|
## When permission prompts appear
|
|
|
|
Enabled is an availability switch, not a security review or a grant. A lazy
|
|
plugin can become enabled without starting code. Its first command/provider use
|
|
starts the runtime; required permissions are authorized at that activation
|
|
boundary. Optional permissions are requested when a broker operation needs them.
|
|
Missing/denied decisions fail closed. Never interpret an Enabled badge as proof
|
|
that terminal, credential, network or filesystem access has been approved.
|