@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-publish-security/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: mdk-publish-security
+description: >
+  Run the pre-publish security audit for every publishable @tetherto/mdk-*
+  package (or any non-private package in an npm monorepo). Use when preparing an
+  npm release, when asked to "security check the packages", "audit before
+  publish", "run the publish checklist", or to review packages for auth bypass,
+  injection, command execution, path traversal, SSRF, prototype pollution,
+  unsafe deserialization, secret exposure, crypto mistakes, insecure defaults,
+  RPC trust boundaries, privilege escalation or TOCTOU issues, or to check
+  that packed tarballs install and import cleanly, what consumers get from
+  npm audit without the root overrides, and who owns the npm scope.
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.10.0"
+license: Apache-2.0
+---
+
+# Pre-publish security audit
+
+Produces one Markdown report listing every publishable package, every check run
+on it, and the issues that must be fixed before `npm publish`. The checks combine
+the repo's `PUBLISH_CHECKLIST.md` (security section + per-package extras) and the
+publish blockers in `NPM_PACKAGES.md` with a manual review for 18 vulnerability
+classes ([`references/vuln-classes.md`](./references/vuln-classes.md)).
+
+This skill never edits package source, never publishes, and never runs install
+scripts of dependencies. Without `--smoke` it only reads the checkout and writes
+the report. **`--smoke` is not read-only:** `npm pack` runs each package's *own*
+`prepack`/`prepare` script (for example it rebuilds `packages/mdk-skill/dist/`),
+and the smoke step then installs the tarballs into a temp directory outside the
+repo and imports every package entry point and runs every `bin`. That executes
+the packages' code, so only run `--smoke` on a checkout you trust.
+
+## 1. Inventory
+
+From the repo root:
+
+```bash
+git ls-files '*package.json' | grep -Ev '(^|/)(node_modules|dist|templates|fixtures?)/' \
+  | xargs grep -L '"private": true'
+```
+
+The filter drops scaffolding templates and generated output, which are not
+packages. The scan script applies the same filter.
+
+Cross-check against the table in `NPM_PACKAGES.md` (if present). A package that
+is publishable but missing from the doc, or vice versa, is itself a finding.
+
+## 2. Mechanical scan (all packages, one command)
+
+```bash
+SCAN_DIR="$(mktemp -d)"   # private dir; never a fixed /tmp path
+node <this-skill>/scripts/scan-packages.mjs --audit --smoke --registry --out "$SCAN_DIR/mdk-scan.md"
+node <this-skill>/scripts/scan-packages.mjs --audit --smoke --registry --json --out "$SCAN_DIR/mdk-scan.json"
+# one package: --pkg backend/core/gateway   (repeatable)
+# keep the smoke project for `npm ls <dep>`: --keep-smoke
+```
+
+`--out` refuses to overwrite an existing file or follow a symlink. `--audit`,
+`--smoke` and `--registry` need network; without them the scan is offline. It runs `npm pack --dry-run --ignore-scripts` per package and checks,
+on exactly the files that would ship. "Blocker" refers to the section of that
+name in `NPM_PACKAGES.md`:
+
+| Check | Source | What fails |
+| --- | --- | --- |
+| `files-allowlist` | Blocker "no `files` allowlist" / checklist "Tarball contents" | No `files` field |
+| `tarball-contents` | Checklist "Tarball contents" | tests, mocks, fixtures, db/, `.env`, keys, real `config/*.json`, `.sh` in the tarball |
+| `escaping-import` | Blocker "relative `require()`s" | Literal `require('../..')` that resolves outside the package dir |
+| `undeclared-dep` | Blocker "missing dependency declarations" / "Tarball smoke test" | Bare import not in `dependencies` (dev-only counts as missing) |
+| `dep-source` | Checklist "Versions and lockfile" | `file:`/`workspace:`/`link:`/git deps in a published manifest |
+| `loose-range` | Checklist "Version ranges" | `*`, `latest`, `x` or unbounded `>=` in `dependencies` (high for the package's own scope) |
+| `private-dep` | Checklist "Version ranges" | Depends on a package that is `"private": true` in this repo |
+| `dev-peer` | Checklist "Version ranges" / UI class U10 | A dev tool (`vitest`, `jest`, `@testing-library/*`, `vite`, `typescript`, …) is a required `peerDependency`, so npm 7+ installs it for every consumer |
+| `root-override` / `package-overrides` | Checklist "Consumer-view audit" | A dep the root `overrides` patches, or `overrides` in the package itself — neither reaches consumers |
+| `publish-access` | Blocker "scoped packages publish as restricted" | Scoped package without `publishConfig.access` |
+| `repository` | Blocker "missing `repository` metadata" / provenance | No `repository` |
+| `prepack-build` | Blocker "no pre-publish build" | `main`/`bin` points at missing build output with no `prepack` |
+| `entry-missing` | Checklist "Tarball smoke test" | A `main`, `exports` or `bin` target is not in the tarball |
+| `bin-shebang` | Checklist "Tarball smoke test" | A `bin` file without a `#!` line |
+| `exports-map` | Hygiene (low) | No `exports` map, so every shipped file is importable |
+| `install-scripts` | Checklist "Install scripts" | `preinstall`/`install`/`postinstall` |
+| `secrets` | Checklist "Secrets" | Key/token patterns, hard-coded credentials, private IPs, internal hosts |
+| `npm-audit` | Checklist "Dependency audit" (`--audit`) | Moderate+ advisories in prod deps of that workspace |
+| `smoke-pack` / `smoke-install` / `smoke-import` / `smoke-bin` | Checklist "Tarball smoke test" (`--smoke`) | Packs every package, installs all tarballs together in a temp project outside the repo, imports each `main`/`exports` entry and runs each `bin --help`. Catches runtime-built paths the static `escaping-import` check misses. A load-time throw that is not a missing module is reported low — confirm it is intentional |
+| Consumer-view audit | Checklist "Consumer-view audit" (`--smoke`) | `npm audit --omit=dev` in the smoke project; repo-level line naming the vulnerable packages. The workspace audit can be clean while this is not |
+| `registry-unclaimed` / `registry-version` / `registry-owner` | Release checks (`--registry`) | Name not on npm yet; version already published; published name points at a different repository (squat). Also reports `npm whoami` and how many packages the scope already holds |
+| SAST leads | Checklist "Static analysis" | Grep hits per vulnerability class in shipped runtime code, including the UI classes (`xss` HTML sinks, `url` navigation sinks and `_blank` without `noopener`, `browser-storage`, `postmessage`) — **triage, do not report raw** |
+
+Then run the repo-wide checks the script does not cover, and record the outcome
+(including "tool not installed" — never silently skip):
+
+```bash
+npm audit --audit-level=moderate                        # root, all workspaces
+npm audit signatures                                    # registry signatures of installed deps
+npx --yes audit-ci@7.1.0 --config .github/scripts/audit-ci.jsonc                 # downloads; needs network
+npx --yes license-checker@25.0.1 --production --onlyAllow 'Apache-2.0;MIT;ISC;BSD-2-Clause;BSD-3-Clause;0BSD;BlueOak-1.0.0;CC0-1.0;Python-2.0;Unlicense' --excludePrivatePackages   # downloads; needs network
+gitleaks detect --no-banner                             # if installed; also on each extracted tarball
+semgrep --config p/javascript --config p/nodejs <pkg>   # if installed
+grep -rn 'uses:' .github/workflows | grep -v '@[0-9a-f]\{40\}'   # actions not pinned to a SHA
+git diff <lastTag> -- '**/package.json'                 # new dependencies since last release
+npm view <dep> time.modified deprecated                 # per new dep: age (<7 days is a flag) and deprecation
+npm sbom --omit dev --sbom-format cyclonedx -w <name>   # attach one SBOM per package to the report
+```
+
+`audit-ci` and `license-checker` are not repo dependencies, so `npx` downloads
+and runs them. Keep the exact versions above (bump only to a release that is at
+least two weeks old, checked with `npm view <pkg> time --json`), never drop the
+`@version`, and record "not run (no network)" when offline.
+
+Scope and account checks need `npm login` as a publisher. Record "not run" if
+nobody with publish rights is available; never infer ownership from 404s:
+
+```bash
+npm whoami
+npm org ls <scope-without-@>                 # you are a member with publish rights
+npm profile get                              # "two-factor auth" is auth-and-writes
+npm access get status <name>                 # after first publish: public as intended
+```
+
+If `--registry` shows the scope has no packages and cannot be listed, the scope
+may be unclaimed. Anyone can then register it, and every doc that says
+`npm install @scope/...` installs their code. Report it as **High** until the
+org exists.
+
+`npm` may be a shell alias/function in the user's profile; scripts call the
+binary directly, so do the same (`command npm …`) when results differ.
+
+## 3. Manual review (per package, 18 classes + UI classes for browser packages)
+
+Mechanical checks cannot find auth bypasses or SSRF. For each package:
+
+1. Read its `package.json`, README and entry point; list its boundaries using the
+   table in [`references/vuln-classes.md`](./references/vuln-classes.md).
+2. Enumerate every route, RPC handler, action, MCP tool and exported function
+   that accepts external data. Follow each to its sinks (fs, process, network,
+   storage, logs, responses).
+3. Walk all 18 classes, and for browser packages (`ui/packages/*`) also the UI
+   classes U1–U12 in the same reference. Treat device, pool and LLM strings rendered
+   by the UI as attacker-controlled. Use the package's SAST leads from step 2 as starting
+   points, and read the surrounding code before deciding.
+4. Run the package-specific extras from `PUBLISH_CHECKLIST.md` → "Extra checks
+   by package" (e.g. gateway: every route requires auth, body/rate limits, CORS,
+   plugin resolution confined to allowed roots; workers: Modbus write allowlist,
+   no shell interpolation of miner commands, TLS to pools; mcp: `safety` flags).
+5. For each class record pass / issue / n/a. An issue needs `file:line`, who the
+   attacker is, what they gain, and the fix.
+
+With many packages, fan this out: one subagent per package (or per small group of
+similar workers) with the package path, its scan section, and
+`references/vuln-classes.md`. Have each return structured findings; verify every
+Critical/High yourself by reading the cited lines before it goes in the report.
+
+**Do not** report: grep leads you have not read, issues only reachable from
+tests/mocks that do not ship (report the *shipping* of them instead), or style
+nits. **Do** report false-negative risk: code the review could not cover (e.g. a
+package whose source is not in the tarball, like a TS `dist/`).
+
+## 4. Report
+
+Write `PUBLISH_SECURITY_REPORT.md` at the repo root (or where the user asks):
+
+1. **Header** — date, branch, commit, version, tools run and their versions, tools
+   unavailable.
+2. **Summary table** — one row per package: blockers / high / medium / low,
+   verdict (*Ready* / *Fix before publish* / *Blocked*).
+3. **Repo-wide results** — audit, signatures, audit-ci, licences, secrets,
+   workflow pinning, SAST availability.
+   Include the smoke install result, the consumer-view audit, and the registry
+   and scope results.
+4. **Per package** — a checklist of every step executed with its result (✅ / ❌ /
+   ⚠️ / n/a), then "Issues to fix before publishing" ordered by severity, each with
+   `file:line`, impact, and fix.
+5. **Cross-cutting fixes** — the same issue in many packages, stated once.
+
+Keep the issue list to things that must change. Link the checklist and
+`NPM_PACKAGES.md` instead of repeating them.

package/dist/skills/mdk-publish-security/references/vuln-classes.md

@@ -0,0 +1,151 @@
+# Vulnerability classes and MDK trust boundaries
+
+The manual-review half of `mdk-publish-security`. For each publishable package, walk
+every class below, starting from the package's **entry points** (the boundaries
+listed first), not from the grep leads. A grep lead tells you where to look; a
+finding needs a concrete attacker, a reachable path and an impact.
+
+## Where attacker-controlled data enters MDK
+
+| Boundary | Packages | Who can send data | Notes |
+| --- | --- | --- | --- |
+| Gateway HTTP (Fastify routes, plugin routes, cached routes, static files, OAuth callback) | `mdk-gateway`, `mdk-core` (`startGateway`) | Any network peer that reaches the bind address; authenticated operators | Every route needs auth + schema validation + body/rate limits |
+| MCP tools (stdio / HTTP via `hono`) | `mdk-mcp` | The LLM driving the tools — and therefore anything that reaches its context (device names, logs, pool data) | Treat tool arguments as untrusted; write/command tools need explicit authorisation and must honour manifest `safety` flags |
+| HRPC / `@hyperswarm/rpc` over the DHT (Kernel ↔ Worker, client ↔ Kernel) | `mdk-kernel`, `mdk-client`, `mdk-worker`, `mdk-core`, all workers | Any DHT peer that knows/derives the public key, unless the whitelist rejects it | Check: public-key whitelist enforced *before* the handler runs, envelope validated, unknown actions rejected, payload size bounded |
+| Device / vendor responses (miner CGMiner API, Modbus/TCP registers, container HTTP APIs, pool REST APIs) | all `mdk-worker-*` (private today; review if one becomes publishable) | A compromised or spoofed device, a MITM on plain-http LAN traffic, the pool/vendor | Responses flow into telemetry, alerts, UI and MCP tool output — validate types and sizes, never `eval`/interpolate them |
+| Config files and env (`config/*.json`, `mdk.yaml`, env vars) | all | Local operator (trusted) but often copied from examples | Insecure *defaults* matter here: what happens when a field is missing |
+| CLI arguments and scaffold names | `mdk-cli` | The local user, or a script/agent invoking `mdk` | Names reach paths, `package.json`, shell hints |
+| Skill content consumed by coding agents | `mdk-skill` | Whoever authors the skill text; the agent executes it | Instructions must not tell an agent to run destructive or network-fetching commands |
+| npm consumers (the SDK surface itself) | all | Third-party apps that `require()` the package | Exported APIs must not trust caller input for paths, URLs, or shell; defaults must be safe when options are omitted |
+| Browser: data rendered by UI packages (device, container, PDU and pool names, telemetry keys, alerts) | `ui/packages/*` (`mdk-react-devkit`, `mdk-react-adapter`) | Whoever can name or rename a device, a compromised or spoofed worker or device, a third-party worker plugin | Rendered in the operator's authenticated session, so an HTML sink is privilege escalation into device control |
+| Browser: LLM output streamed to the UI | `mdk-ui-agent` | Anything that reaches the model's context (prompt injection through device, pool and log data) | Treat every token, tool name, tool arg and tool result as attacker-controlled |
+| Browser: URL, storage and session (`?authToken=`, `localStorage`, `sessionStorage`) | `mdk-ui-foundation`, `mdk-react-adapter`, `mdk-ui-agent` | Anyone who can get an operator to open a link; any same-origin script; the next user of a shared browser | Session adoption, token persistence and refresh, cross-user leftovers |
+
+## The 18 classes
+
+For each, the MDK-specific questions to answer. Record **pass**, **issue** (with
+`file:line`, attacker, impact, fix) or **n/a** (with the reason) per package.
+
+1. **Authentication/authorization bypass** — Can a route or RPC handler be reached
+   with no token, an expired token, or a token for another role? Does the DHT
+   whitelist accept an empty list as "allow all"? Are there `skipAuth`/dev flags
+   that survive into production?
+2. **Missing authorization on API/RPC methods** — Enumerate every registered
+   route, RPC `respond()` / action handler and MCP tool. Mark which check gates it.
+   Commands that change device state (reboot, power mode, pool switch, Modbus
+   write, factory reset) need a write/admin permission, not just "authenticated".
+3. **Unsafe input handling** — Are params validated against the contract/manifest
+   (type, range, enum, length)? Unbounded arrays, time ranges, page sizes,
+   `parseInt` without radix/range, regex built from input (ReDoS).
+4. **Injection** — SQL (`better-sqlite3`/sqlite queries with template literals),
+   LevelDB/Hyperbee key injection via unescaped prefixes, log injection, header
+   injection, template/HTML injection into UI-facing strings, prompt injection into
+   MCP tool output.
+5. **Command execution** — `child_process`, `shell: true`, `eval`, `new Function`,
+   `vm`, dynamic `require()`/`import()` of a path that a config, manifest or request
+   can influence (plugin loaders!).
+6. **Path traversal** — Plugin `package`/directory resolution, static file serving,
+   store/db dirs, scaffold targets, skill install targets, any `path.join(base, x)`
+   without `path.resolve` + prefix check. Watch symlinks.
+7. **SSRF** — Device `address`/`port` and pool URLs supplied via RPC
+   (`registerThing`, config updates) or HTTP, then fetched by the worker. Can a
+   caller point a worker at `169.254.169.254`, localhost admin ports or an internal
+   host? Redirect following?
+8. **Prototype pollution** — Deep merge / `Object.assign` / `obj[key] = v` with keys
+   from JSON payloads, query strings, config or device responses. `__proto__`,
+   `constructor.prototype`.
+9. **Unsafe deserialization** — `JSON.parse` of peer data without try/catch or size
+   cap (crash = DoS of the kernel), `v8.deserialize`, YAML `load`, msgpack/compact
+   encodings from untrusted peers, reviving class instances.
+10. **Sensitive information exposure** — Stack traces, internal paths, config,
+    device passwords or pool credentials returned in API/RPC/MCP responses; verbose
+    error messages; debug endpoints.
+11. **Cryptographic mistakes** — TLS verification disabled, weak hashes/ciphers,
+    `Math.random` for ids/tokens/nonces, non-constant-time token compare, keys or
+    seeds derived from predictable input, key material written world-readable.
+12. **Insecure defaults** — Bind `0.0.0.0` by default, auth off when config omits
+    it, permissive CORS, debug on, default passwords (`admin`/`root`) in shipped
+    config/README examples, plain-http to devices/pools, unlimited body size.
+13. **Trust-boundary problems between SDK and consumers** — Does an exported
+    function trust its caller for something it should validate (paths, URLs,
+    plugin dirs)? Does the SDK mutate caller-owned objects or globals? Does it
+    `process.exit()`, install signal handlers, or read env vars the consumer did not
+    opt into? Peer/optional deps that change security posture?
+14. **Network/RPC endpoints accepting attacker-controlled data** — List each
+    listener (HTTP port, RPC server key, MCP transport, mock servers that might be
+    started in prod) and what reaches it without auth.
+15. **Privilege escalation** — Can a read-only/operator role invoke admin actions?
+    Can a worker (lower trust) make the kernel act on another worker's devices? Can
+    a plugin escalate to gateway-wide config?
+16. **Race / TOCTOU** — `existsSync` then write; check-then-act on command state
+    machines; concurrent state pull / timer reset; action approval flows where state
+    can change between approve and execute; temp files with predictable names.
+17. **Dangerous filesystem operations** — `rm -rf`/`rmSync({recursive})` on a path
+    derived from config or input, `chmod`, symlink following, writing into
+    `node_modules`, overwriting user files during scaffold/install.
+18. **Secrets exposed through logs or API responses** — Logging of tokens,
+    `Authorization` headers, device passwords, pool API keys, DHT seeds/secret keys,
+    full config objects, or request bodies containing any of them; audit logger
+    redaction.
+
+## UI classes (browser packages)
+
+For packages that run in a browser (`ui/packages/*`), walk these **in addition to** the
+18 classes above. Most of the 18 are written for servers, so several are `n/a` for UI
+code; these cover what replaces them. Record pass / issue / n/a in the same way.
+
+- **U1. XSS.** `dangerouslySetInnerHTML`, `innerHTML`/`outerHTML`/`insertAdjacentHTML`,
+  HTML built as strings (chart tooltips, formatters), markdown or HTML rendering
+  (`rehype-raw`, custom remark/rehype plugins), SVG, `style` attributes built from data.
+  Trace every device, pool, alert or agent string to the sink.
+- **U2. URL injection.** `href`/`src`/`action` built from data (`javascript:`, `data:`),
+  `window.open`, `location` assignments, redirect-after-login paths (`//host`), and
+  remote resources loaded from data (`<img>` in rendered markdown is an exfiltration
+  channel that needs no click).
+- **U3. Browser token and credential handling.** Tokens accepted from the URL (any
+  `?token=` adopted without a `state` nonce is login CSRF / session fixation), tokens
+  in `localStorage` (readable by any XSS), unbounded refresh, sign-out that only
+  clears locally, roles parsed client-side and re-sent to the server.
+- **U4. CSRF and fetch credentials.** `credentials: 'include'`, cookie auth across
+  origins, an API base URL taken from untrusted input, plain-`http` defaults that
+  carry a bearer token.
+- **U5. postMessage, iframes, `window.opener`.** Message handlers without an origin
+  check, embedded frames, `target="_blank"` without `rel="noopener"`.
+- **U6. ReDoS and expensive client-side parsing.** Regexes or parsers run on server or
+  stream data (unbounded SSE buffers, rescans per chunk), and user text sent to the
+  server as a raw regex.
+- **U7. Prototype pollution and data-derived keys.** Query/filter builders that turn
+  user input into field paths or operators, deep merges of server data, and plain
+  objects indexed by server-chosen keys (`__proto__`, `constructor`) that crash renders.
+- **U8. eval and dynamic code.** `eval`, `new Function` (also forces CSP `unsafe-eval`),
+  `import()` of computed specifiers.
+- **U9. Sensitive data in client logs and storage.** `console` output, telemetry or
+  error reports carrying tokens or fleet data; transcripts, drafts or queued actions
+  persisted across logout or shared between users of one browser.
+- **U10. Runtime supply chain.** Unexpected or heavy runtime dependencies, required
+  `peerDependencies` that are dev tools (npm 7+ installs them for every consumer),
+  scripts, styles or fonts loaded from a CDN, licences of shipped assets (fonts).
+- **U11. SSR and Node safety.** `window`/`document`/`localStorage` touched at import
+  time; `dist/` ESM with extensionless or directory imports (works only in bundlers,
+  fails under Node, SSR and Jest); JSON exports that need `with { type: 'json' }`.
+- **U12. What ships.** Tests, fixtures, test utilities importing `vitest`, compiled
+  examples, source maps with absolute local paths, examples using monorepo-only
+  aliases.
+
+Also check per UI package:
+- **Peer vs dependency.** React, `react-dom`, `@tanstack/react-query` and `zustand`
+  should be peers when the package shares their context or store with the host.
+- **`sideEffects`.** It must match what the package does at import time (CSS imports,
+  singletons).
+- **React peer range.** Check it is the range you intend to support.
+- **Public API disclaimers.** Client-side permission helpers must say they only hide
+  UI and do not enforce anything.
+
+## Severity guide
+
+| Severity | Meaning | Publish? |
+| --- | --- | --- |
+| **Critical** | Remote, unauthenticated code execution, auth bypass, or device control | Block |
+| **High** | Authenticated privilege escalation, SSRF/path traversal with real reach, secret leak, a tarball that fails at runtime or ships secrets | Block |
+| **Medium** | Insecure default with a safe override, DoS by an authenticated peer, missing hardening that the checklist requires | Fix before publish unless explicitly accepted |
+| **Low / Info** | Defence in depth, hygiene, docs | Track |