@spec load_envelope(Path.t()) :: {:ok, envelope()} | {:error, envelope_error()}

Loads and decodes the signature envelope from priv/mob_plugin.sig.

Returns the full envelope map (v2 shape) on success, or a distinguished error. A v1 envelope on disk is reported as :envelope_v1_unsupported so the caller can print a re-sign hint — v1 required the eval'd manifest to verify, which is the bug MOB-74 closes.

@spec load_pubkey(Path.t()) ::
  {:ok, MobDev.Plugin.Crypto.pub_key()} | {:error, pubkey_error()}

Loads the raw 32-byte public key from priv/mob_plugin.pub.

Format: a single line of base64 (with = padding) of the raw 32-byte Ed25519 public key, optionally followed by a trailing newline. Plain text so plugin authors can cat it or paste it into a release note.

@spec load_signature(Path.t()) ::
  {:ok, MobDev.Plugin.Crypto.signature()} | {:error, envelope_error()}

Back-compat shim for mob 0.8.x and the SignatureGate.maybe_print_unsafe_banner/1 path, both of which used the v1 helper that returned just the raw signature. Now returns the same 64-byte signature but extracted from a v2 envelope. Callers that need the full envelope should use load_envelope/1.

@spec load_verified(
  Path.t(),
  keyword()
) :: {:ok, map() | nil} | {:error, verify_error() | String.t()}

Verifies the plugin, then loads and evaluates the manifest.

This is the safe consumer-side path: if verify_plugin/1 refuses, Manifest.load/1 is never called and Code.eval_file/1 on the potentially-malicious priv/mob_plugin.exs never runs.

Options

• :acknowledged_unsafe (default false) — when true, an unsigned plugin ({:error, :missing_signature}) is loaded anyway. This is the documented escape hatch for :acknowledge_unsafe_plugins (see SignatureGate.check_plugin/4) — the user has explicitly opted into running an unsigned plugin's manifest, and the SignatureGate banner already warns them. Every OTHER failure (:invalid_signature, :missing_pubkey, :envelope_v1_unsupported) still refuses the eval — those are the tamper / mis-key cases, not the "unsigned during dev" case.
• :scms, :lock, :deps_path, :trust_map — provenance inputs for the transitional v1 rule (see MobDev.Plugin.V1Transition); default to the current Mix project's values.

A v1 envelope is handed to MobDev.Plugin.V1Transition.load/2, which evaluates the manifest only for a hexpm Hex dependency whose public key is trusted, then verifies the v1 signature (MOB-287). Every other v1 envelope is refused unevaluated with :envelope_v1_unsupported.

For plugins with no priv/mob_plugin.exs at all (tier-0 plugins), returns {:ok, nil} without requiring a signature — the acknowledged_unsafe flag has no effect here (no manifest to load).

@spec verify_plugin(Path.t()) :: :ok | {:error, verify_error()}

Verifies that the plugin in plugin_dir has a valid v2 signature and that the on-disk files match what the author signed.

Steps 1–4 (see the moduledoc) run entirely off the envelope's embedded file_hashes list — the manifest is one of those files, and rehashing its bytes on disk detects tampering without any Code.eval_file call. That is the MOB-74 fix: verification is safe to run before eval, closing the RCE window where a malicious priv/mob_plugin.exs could execute arbitrary code during plugin activation.

For a signature carrying the build-input coverage marker (MOB-297), step 5 then evaluates the manifest — only after its bytes matched the signed hash and the signature verified — to recompute Sign.build_inputs/2 and refuse any build input the signature omits.

Returns :ok on success or one of the distinguished error reasons (see verify_error/0). The caller is responsible for any trust decision; this function only proves that the bytes on disk match what the plugin author signed.