docs: plugin trust policy (fail-closed default), capability tiers, signing

- document Ed25519 signing, digest binding, fail-closed allow_unsigned_host_risk default; capability risk tiers; system/wasm/worker boundaries

Author: lr00rl

README.md

@@ -4,9 +4,9 @@ This directory is the starting point for new Lattice extensions.
 
 Plugin categories:
 
-- `system-go/` - trusted system plugin process template for host operations.
+- `system-go/` - trusted first-party system plugin process template for host operations.
 - `worker/` - capability-limited dashboard/server Worker template.
-- `wasm/` - future Wasm plugin template notes.
+- `wasm/` - future sandboxed third-party Wasm plugin template notes.
 
 ## Manifest
 
@@ -17,13 +17,108 @@ Every plugin must declare an explicit capability list:
   "id": "example.nft-guard",
   "name": "Example nft Guard",
   "type": "system",
+  "version": "0.1.0",
+  "publisher": "latticenet",
+  "entrypoint": "system-go/lattice-plugin-example",
+  "digest_sha256": "<artifact sha256 hex>",
+  "signature_ed25519": "<base64 ed25519 signature>",
   "capabilities": ["network:plan"]
 }
 ```
 
 Unknown capabilities are rejected by the server. Dangerous capabilities such as
 `network:apply` should never be granted to third-party plugins by default.
 
+Manifest identity is intentionally strict:
+
+- `id` is a stable lowercase identifier using only `a-z`, `0-9`, `.`, and `-`;
+  it must not contain whitespace, slashes, path traversal, or uppercase letters.
+- `name` must be printable and at most 80 characters.
+- `capabilities` must be non-empty and must not contain duplicates.
+- `version` and `entrypoint` are part of the public plugin contract even when a
+  current template does not need generated code yet.
+- `publisher` identifies the signer/trust root. Production loaders should
+  accept high-risk system plugins only from trusted publishers.
+- `digest_sha256` is the lowercase hex SHA-256 of the plugin artifact/package.
+- `signature_ed25519` signs the canonical Lattice plugin payload for
+  `id`, `name`, `type`, `version`, `entrypoint`, `publisher`, `digest_sha256`, and
+  capabilities. It prevents replacing the artifact or reusing a signature for a
+  different plugin id.
+
+## Capability Guide
+
+Low-risk read capabilities:
+
+- `node:read`
+- `monitor:read`
+- `audit:read`
+- `kv:read`
+- `static:read`
+- `task:read`
+
+Operator-write capabilities:
+
+- `kv:write`
+- `worker:route`
+- `notify:send`
+
+High-risk host capabilities:
+
+- `node:admin`
+- `monitor:admin`
+- `ddns:admin`
+- `tunnel:admin`
+- `static:write`
+- `task:run`
+- `network:plan`
+- `network:apply`
+
+Type restrictions:
+
+- `system` plugins may request high-risk capabilities, but should be reserved
+  for first-party or operator-audited plugins.
+- `worker` plugins may request only `worker:route`, `kv:read`, and
+  `static:read`.
+- `wasm` plugins may request read and operator-write capabilities, but may not
+  request high-risk host capabilities.
+
+Third-party plugins should start with read-only capabilities. First-party system
+plugins may request high-risk capabilities only when their actions produce an
+auditable dry-run plan and go through the Lattice approval flow.
+
+`task:read` is intentionally separate from `task:run`: reading task metadata and
+results must not imply the ability to queue remote execution.
+
+## Signing Model
+
+Development manifests may omit `digest_sha256` and `signature_ed25519`, but a
+production Lattice loader should verify them for any host-risk capability such as
+`network:plan`, `network:apply`, `task:run`, `ddns:admin`, or `tunnel:admin`.
+
+The server-side verifier expects:
+
+- `publisher` to match a trusted Ed25519 public key configured by the operator.
+- `digest_sha256` to match the exact plugin artifact bytes.
+- `signature_ed25519` to verify against the canonical Lattice signing payload.
+
+Trust policy JSON:
+
+```json
+{
+  "allow_unsigned_host_risk": false,
+  "trusted_publishers": {
+    "latticenet": "base64-raw-ed25519-public-key"
+  }
+}
+```
+
+> Fail-closed by default: omitting `allow_unsigned_host_risk` (or setting it
+> `false`) requires a trusted-publisher Ed25519 signature for **every** host-risk
+> plugin. Set it `true` only for local development on a host you fully control.
+
+Do not sign unpacked source directories casually. Build a deterministic artifact
+first, hash that artifact, then sign the manifest payload for that digest.
+
 ## System Plugin Contract
 
 The bootstrap template uses newline-delimited JSON over stdio:
@@ -42,4 +137,3 @@ Output:
 
 Future Lattice releases can replace stdio with gRPC/hashicorp-go-plugin while
 keeping the same capability and approval semantics.
-

SECURITY.md

@@ -8,9 +8,24 @@ Rules:
 - No process execution in third-party plugins.
 - No environment variable access by default.
 - No arbitrary network access by default.
-- `network:apply`, `task:run`, and `static:write` must be treated as high-risk.
+- Manifest ids must be stable lowercase identifiers, never paths or user-facing
+  labels. Capability lists must be explicit, non-empty, and duplicate-free so
+  reviews and audit events cannot disagree about what was granted.
+- Production manifests for high-risk/system plugins must include a trusted
+  `publisher`, artifact `digest_sha256`, and `signature_ed25519`. Unsigned
+  development manifests are acceptable only before installation/loading.
+- `network:apply`, `task:run`, `node:admin`, `ddns:admin`, `tunnel:admin`,
+  `monitor:admin`, `network:plan`, and `static:write` must be treated as high-risk.
+- `task:read` is read-only and must never grant task creation or remote
+  execution.
+- `worker` plugins may only declare `worker:route`, `kv:read`, and
+  `static:read`.
+- `wasm` plugins may not declare high-risk host capabilities.
+- High-risk capabilities require a trusted `system` plugin.
+- Plugins that affect a node must be constrained by the caller's node allowlist.
+- Webhook-style plugins must use the server's guarded outbound HTTP client; they
+  must not dial loopback, private, link-local, metadata, or special-use ranges.
 - All privileged operations must be auditable by `lattice-server`.
 
 System plugins are trusted built-ins. Third-party plugins should target the
 future Wasm host or the restricted Worker interface.
-

manifest.json

@@ -2,6 +2,8 @@
   "id": "example.lattice-plugin",
   "name": "Example Lattice Plugin",
   "type": "system",
+  "version": "0.1.0",
+  "publisher": "latticenet",
+  "entrypoint": "system-go/lattice-plugin-example",
   "capabilities": ["network:plan"]
 }
-

wasm/README.md

@@ -8,7 +8,9 @@ sandbox. Lattice will use an explicit host API model:
 - No environment variable access.
 - No arbitrary network access.
 - KV/static/notify APIs only when the manifest grants the matching capability.
+- No high-risk host capabilities: `node:admin`, `monitor:admin`,
+  `ddns:admin`, `tunnel:admin`, `static:write`, `task:run`,
+  `network:plan`, or `network:apply`.
 
 The current MVP validates manifests but does not execute Wasm yet. Keep new
 third-party plugin designs compatible with this capability model.
-

worker/README.md

@@ -21,3 +21,12 @@ Suggested manifest:
 }
 ```
 
+Worker plugins are deliberately narrow. The server accepts only these
+capabilities for `type: "worker"`:
+
+- `worker:route`
+- `kv:read`
+- `static:read`
+
+Use a trusted `system` plugin when a feature needs host, process, network-plan,
+DDNS, tunnel, or remote-task capabilities.