plugins: disclose filesystem, network, environment, and subprocess access

[bomly-guy]

Summary

Add optional permission/capability disclosure to managed-plugin package manifests and surface it during install, enable, verify, doctor, and inspection flows.

This is disclosure, not sandbox enforcement.

Current trust model

docs/PLUGINS.md correctly states that managed plugins are native executables and are not sandboxed: they can access the filesystem, environment, network, and subprocesses with the invoking user's authority.

internal/plugin/types.go:Manifest currently describes identity, versions, runtime, entrypoints, and provenance, but cannot disclose expected access. Users therefore cannot distinguish a plugin that only reads the repository from one that also writes files, contacts arbitrary hosts, reads named environment variables, or starts tools.

A manifest is authored by the plugin publisher, so this information is untrusted self-attestation. It must never be displayed as an enforcement guarantee.

Proposed disclosure classes

The ADR should settle the exact schema, but it needs to represent at least:

• repository/filesystem read and write intent;
• network destinations or destination classes;
• environment-variable names or declared environment access;
• child-process execution and, where practical, expected commands/tools.

Fields must be bounded, normalized, deterministically ordered, and extensible. An absent disclosure on a legacy package means unknown/unrestricted, never "no access."

Ownership decision

The package manifest type is currently CLI-owned, while PackageManifestSchemaVersion lives in bomly-sdk. Before implementation, apply the SDK source-of-truth rule in an ADR:

• if permission declarations and validation are part of the public plugin package contract, define the durable shared types/validation in the SDK first and link the prerequisite SDK issue/PR here;
• keep CLI presentation, prompts, installation policy, and command behavior in this repository;
• do not maintain duplicate validators in SDK and CLI.

Any SDK change must be released SDK-first, then adopted here by tag.

Acceptance criteria

• An ADR under dev-docs/adr/ records ownership, schema semantics, normalization, legacy behavior, and the explicit distinction between disclosure and enforcement.
• Package manifests can optionally declare the four access classes above.
• Validation bounds entry counts and string sizes, rejects malformed host/env/path entries, and normalizes deterministically.
• Missing disclosure is represented in code and UI as unknown/unrestricted.
• Install and enable flows show the disclosure before trust is granted, without claiming the access is enforced.
• plugin list --json, detailed inspection, plugin verify, and plugin doctor expose the declared/unknown state.
• Human-readable output clearly labels publisher declarations as unverified.
• Existing manifests continue to decode and install under the documented legacy policy.
• Manifest fixtures, archive/install tests, validation tests, JSON output tests, and docs are updated.
• Generated schema/reference artifacts are regenerated where applicable.
• No filesystem/network/env/process restriction is claimed or silently implemented by this issue.

Security notes

• A declaration is not evidence that runtime behavior matches it.
• Checksums verify artifact integrity, not behavioral safety.
• Do not log environment values, credentials, tokens, or secret file contents.
• Network destinations should be treated as descriptive patterns unless and until a separate enforceable sandbox exists.

Out of scope

• OS sandboxing, containers, seccomp, network proxies, or filesystem namespaces.
• Automatically granting or denying host services through HostContext.
• Treating undeclared access as technically blocked.
• Changing Bomly's current native-plugin trust boundary.

Verification

Run:

make test
make build-lite
make generate