NetMesh/docs/plugin-platform/security-and-permissions.md

# Plugin security and permission boundary

Status: phase 3 internal preview (`0.1.0-internal`)

This phase is available only with `NETCATTY_PLUGIN_DEV=1`. It is deliberately
usable by later contribution and Provider phases, but it is not a public plugin
release. There is no renderer permission UI yet. The first-party development
bootstrap injects a native Electron confirmation dialog; embedders that do not
inject a decision provider still fail closed.

## Authority model

Every privileged plugin-to-host method is registered in
`PluginHostRpcRegistry` with one explicit authorization descriptor. Parameters
are validated first; the descriptor is then built without probing protected
host state, and quota and permission middleware run immediately before the
handler. Filesystem and credential existence checks happen only after that
permission boundary. An unclassified method is denied. The only current public
method is bounded, redacted logging.

The host supplies immutable plugin ID, version, runtime ID, placement, manifest,
package root, cancellation signal, active-runtime guard, and security principal.
Plugin payload fields can never replace that identity. The default pre-signature
principal is a hash of plugin ID, declared publisher, and immutable package
SHA-256, so changed unsigned code cannot inherit persistent grants. The
placement seam also accepts a `resolveSecurityPrincipal` function so phase 9 can
substitute a verified publisher-key fingerprint without changing the permission
engine.

The grant key includes:

- plugin ID and permission;
- canonical resource;
- required-versus-optional declaration semantics and declared resource bounds;
- the host-resolved security principal.

Changing any declaration boundary or principal invalidates reuse. A renderer
decision cannot grant a resource broader than the manifest declaration.
Permission prompts use the canonical contract directly: absent operation and
session IDs are omitted, long host-generated operation IDs become stable
SHA-256 identifiers, reasons are bounded, and no request can carry more than
128 canonical resources.
Runtime trust/placement resolves before permission prompts. The special
`runtime.advanced` permission is excluded from generic required-permission
preflight and requested exactly once only when the host actually selects the
utility runtime.

## Grant lifetimes

- `once` applies only to the request waiting on that decision and is not stored.
- `session` is held in memory and requires a host-owned session ID; ending the
  session removes it.
- `application` is held in memory until explicit revoke or shutdown.
- `always` is persisted in `plugin_permission_grants`.

All lifetimes use the same resource-coverage function. Every resource carries
an explicit `exact` or `directory` kind. Only a filesystem `directory` grant
covers descendants with path-boundary comparison; a file remains exact even if
the path is later replaced by a directory. Origins and companions are exact;
`*` is valid only when the manifest declaration also allows it. Concurrent
identical prompts coalesce. Prompt timeout, runtime abort,
cancel, denial, absence of a decision provider, and stale activation all fail
closed. Grant/use/deny/revoke events enter the bounded security audit.

`PermissionRequest` is part of the canonical Schema and carries plugin display
identity, version, runtime placement, permission, canonical resources and their
aligned resource kinds, reason, operation and optional host session. This is
the complete PR-4 UI handoff; the renderer must return the same request ID and
one canonical lifetime decision. The native fallback visibly escapes control,
line-separator, and bidirectional-control characters in every plugin-controlled
display field so untrusted text cannot forge labels or resource lines.

## Host-mediated capabilities

These brokers are the only authority path for ordinary browser plugins. An
advanced utility entrypoint is intentionally different: `runtime.advanced`
means explicit consent to ambient Node, filesystem and network APIs in its
contained process. Fine-grained broker grants do not sandbox that ambient Node
authority. Phase 9 must also require a verified publisher principal before the
advanced path can be publicly enabled.

Required resource-scoped permissions (`network`, filesystem read/write, and
companion execution) must declare non-empty activation-time resource bounds;
the all-resources `*` wildcard is not a valid bound.
The string shorthand remains available only for optional declarations, whose
concrete resource is approved on first use. A package update therefore cannot
activate first and defer a newly required resource decision until later.

Native companions are an advanced-runtime capability. Their manifests require
a Node utility entrypoint plus `runtime.advanced`, and `companion.start` rejects
browser runtime identities before permission middleware can persist a grant.
The first-party placement path selects the utility runtime whenever companions
are declared, including manifests that also provide a browser entrypoint.
The supervisor repeats the placement check immediately before reserving or
spawning a process. Phase 9 adds verified publisher trust to this same boundary.
Privileged Terminal interceptors use the same deterministic utility placement
rule and additionally require their direction-specific interception grant.

### Network

The ordinary browser SDK has no direct network primitive. `network.request` supports
HTTP(S) only, exact origin authorization, bounded headers, a 128 KiB request and
response body, explicit timeout, no URL credentials, no ambient cookies, no
transport headers, and manual redirects. Every redirect origin is authorized.
The SDK forwards the validated request timeout as the host RPC deadline, so the
router cancels stalled broker work at the same boundary.
Cross-origin redirects strip sensitive headers; 301/302/303 transitions do not
replay POST bodies as GET requests.

### Filesystem

Read, write, stat and directory listing require an absolute path. Authorization
first uses only the lexically resolved requested path, including removal of
redundant trailing separators, so an ungranted request cannot probe path
existence, type, symlink targets or real paths. After permission,
the handler resolves the real path and requires it to equal the authorized
resource; callers must therefore supply an already canonical path and symlink
aliases fail closed. File opens use `O_NOFOLLOW` where supported and bind the
opened handle to both the pre-open authorized inode and the current path inode.
Directory listing requires a host adapter that can bind both inode checks and
enumeration to the same native directory handle. Portable Node does not expose
that primitive, so the default implementation fails closed while preserving
the SDK/RPC seam for a native adapter. Reads use the actual handle bytes rather
than trusting a pre-read size, with a 128 KiB cap. Larger payloads use streams.
Arbitrary-path writes currently require an existing regular file and explicit
overwrite; no `O_CREAT` path exists because Node cannot portably bind creation
to an opened parent-directory handle across macOS, Linux, and Windows. A later
native implementation can add secure relative creation behind the same SDK
method. Writes recheck runtime activity immediately before mutation, and
listing is limited to 1,000 entries.

### Secrets and credentials

Secret values are encrypted with Electron `safeStorage`; unavailable OS
encryption or Linux's insecure `basic_text` fallback denies the operation.
SQLite stores ciphertext plus a `SecretRef` containing an opaque random ID and
the non-secret originating key, never plaintext. The key lets lease permission
checks use the same manifest resource as `secrets.get`/`set`; post-permission
lookup revalidates that the random ID still belongs to that key and plugin.
Secret tables and grants are user-owned security
data and do not cascade when a package version is removed.

Plugins can ask `PluginCredentialBroker` for a `SecretLeaseRef`. A lease is
single-consumption, opaque, maximum 60 seconds, and bound to plugin, active
runtime, operation ID, abort signal and secret ownership. Only a host capability
broker can redeem it. A plugin-owned `SecretRef`, a Netcatty-owned opaque
`CredentialRef`, or a lease ID alone is not authority. Netcatty credential
references use an injected main-process resolver. Authorization treats both
secret and credential IDs as opaque identifiers and does not reveal whether
they exist; secret keys are already plugin-declared resources. Ownership,
ID-to-key binding, and existence are checked only after permission,
immediately before lease issue. Plaintext resolves only when the one-use lease
is consumed. This is the stable credential handoff used by
connection/authentication Providers in PR 7. Importer Providers cannot smuggle
hidden built-in plaintext credentials through host drafts; credentials must be
declared as identity/key drafts and then pass through the same host-owned
encrypted persistence and credential-reference flow.

### Companion executables

Only the manifest variant matching the current OS/architecture can start. Its
real path must remain inside the package, be a regular file, and match the
declared SHA-256 immediately before spawn. The host uses an absolute executable,
empty argument vector, private plugin data directory, minimal environment,
`shell:false`, bounded Content-Length JSON-RPC, at most four processes per
runtime and 64 pending calls per process. Companion-to-host methods receive
method-not-found; privileged work remains in the main host brokers.
Timed-out companion RPC identifiers are retired until one late response is
discarded, and the runtime SDK retries a failed stop rather than marking the
handle locally stopped before the host confirms cleanup.
The validated companion request timeout is also forwarded as its host RPC
deadline.

On POSIX, companions start in a dedicated process group; shutdown signals the
whole group, escalates the whole group to `SIGKILL`, and waits until it no longer
exists. Windows uses shell-free `taskkill /T` for both graceful and forced tree
cleanup. A direct parent exit also starts tree cleanup before the handle or
quota monitor is released. An unreaped companion tree is a containment failure
and disables its plugin. Runtime stop events revoke leases and release all owned
companion handles. Disable, restart, upgrade and uninstall wait for that tree
cleanup before returning or mutating package code; a cleanup failure is
persisted as a containment failure and blocks replacement activation.

## Quotas and failure behavior

The raw-message token bucket runs before schema traversal. Capability
concurrency/rate, logging rate, per-category byte windows, companion count and
pending RPC limits bound retained work. Electron process metrics enforce memory
and sustained-CPU policy for browser/utility runtimes and companion processes.
The runtime monitor is attached and takes its first sample immediately when the
BrowserWindow renderer or utility process is created, before initialize or
activation runs. A process policy violation disables and stops only its owning
plugin.

Network, filesystem, secret, credential and companion handlers recheck the
active runtime immediately before commits or returned results. Cancellation,
disable, update, uninstall, quarantine and shutdown therefore cannot resume a
stale privileged operation.

## Initial database policy

The plugin platform has never shipped. The complete current database remains
schema version 1 and includes package/runtime tables plus grants, secrets and
security audit. There is no migration chain. A developer using an older preview
must reset `userData/plugins/plugins.sqlite`; released migrations begin only
after durable user data can exist.

## Downstream contracts

- PR 4 consumes `PermissionRequest`, structured grant lists/revocation, runtime
  events and the existing RPC registry for settings/commands/views. Secret
  settings retain their declared key in `SecretRef` without exposing plaintext.
- PRs 5-6 reuse immutable caller identity, permission middleware, cancellation,
  quotas and runtime-stop cleanup; the direct terminal fast path remains a
  separate MessagePort and must still enforce sensitive-input bypass. Their
  larger payloads use streams rather than the 128 KiB control-plane budget.
- PR 7 consumes operation-bound secret leases and digest-verified companions;
  secret lease authorization uses the declared key while ID ownership remains
  a post-permission lookup. Importers use bounded streams, not directory walks,
  and their draft schemas reject executable startup commands and hidden
  plaintext built-in credential fields before Vault persistence.
- PR 8 stores encrypted sync sidecars in `plugin_sync_sidecars` (no package
  cascade) for non-secret `sync: true` settings plus account/CRDT baselines, and
  transports larger encrypted objects over the existing stream seam. Secret
  settings never enter cloud sidecars.
- PR 9 supplies signed publisher principals and trust policy through placement;
  signed identity changes force a fresh grant instead of widening an unsigned
  grant silently.