diff --git a/SECURITY.md b/SECURITY.md index fd4d0bc..5a0657c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,11 @@ ## Supported Versions -Security fixes are prioritized for the latest published `0.x` release line and `main`. +| Version | Supported | +| --- | --- | +| `0.9.x` | Yes | +| `main` | Yes | +| `< 0.9` | No | This policy covers the published npm packages (`@usejunior/safe-docx`, `@usejunior/docx-mcp`, `@usejunior/docx-core`), the MCP server, and the CLI entrypoint. @@ -21,16 +25,33 @@ Do not open a public issue for an unpatched vulnerability. ## Response Expectations -- Initial acknowledgement target: within 3 business days. +- Initial acknowledgement target: within 2 business days. - Triage and severity assessment target: within 7 business days. +- Status update target for active reports: at least every 7 business days until mitigation or resolution. - Fix timeline depends on severity and complexity. +## Scope + +In scope for this document processing library: + +- arbitrary code execution, command injection, or unsafe parser behavior triggered by opening, comparing, editing, or saving `.docx` files +- arbitrary file read/write, path traversal, zip slip, or temp-file leakage outside the user-requested workspace +- document content disclosure, unexpected network egress, or bypasses of the local-first execution model +- denial-of-service issues caused by hostile Office documents that can exhaust CPU, memory, or disk substantially beyond normal operation +- dependency vulnerabilities with a material confidentiality, integrity, or availability impact + +Not usually treated as security vulnerabilities: + +- formatting bugs, diff quality issues, or tracked-changes mismatches without a confidentiality, integrity, or availability impact +- feature requests, parser edge cases, or hardening ideas without a demonstrated exploit path +- reports against unsupported versions without a reproducible impact on a supported release + ## Disclosure Policy We follow coordinated disclosure. Reporters will be credited in the release notes accompanying the fix unless they prefer anonymity. We will coordinate with reporters on disclosure timing. -## Scope Notes +## Architecture Notes - `safe-docx` is intended for local execution and local file editing workflows. -- All document processing runs locally. No document content is transmitted to external servers. +- All document processing runs locally. No document content is transmitted to external servers by default. - External dependencies are monitored through normal dependency updates and CI. diff --git a/package.json b/package.json index b55cd8e..5cb710b 100644 --- a/package.json +++ b/package.json @@ -74,5 +74,18 @@ "engines": { "node": ">=20" }, + "keywords": [ + "docx", + "word", + "document", + "ai", + "mcp", + "legal", + "contract", + "editing", + "tracked-changes", + "redline", + "safedocx" + ], "license": "MIT" } diff --git a/packages/safe-docx/package.json b/packages/safe-docx/package.json index 3750575..794bc95 100644 --- a/packages/safe-docx/package.json +++ b/packages/safe-docx/package.json @@ -51,6 +51,8 @@ "model-context-protocol", "docx", "word", + "document", + "editing", "document-editing", "tracked-changes", "document-comparison", diff --git a/skills/docx-editing/CONNECTORS.md b/skills/docx-editing/CONNECTORS.md index 659ef44..8359cdb 100644 --- a/skills/docx-editing/CONNECTORS.md +++ b/skills/docx-editing/CONNECTORS.md @@ -2,17 +2,26 @@ How to connect the Safe-DOCX MCP server to your AI editor or desktop client. +## Requirements + +| Binary | Minimum version | Notes | +|--------|-----------------|-------| +| `node` | 18.0.0 | Authoritative from `package.json` engines field | +| `npm` / `npx` | Bundled with Node.js | Only needed for the `npx` connector path | + ## Summary | Property | Value | |----------|-------| | Transport | stdio | -| Command | `npx` | -| Args | `["-y", "@usejunior/safe-docx"]` | +| Command (default) | `npx` | +| Args | `["-y", "@usejunior/safe-docx@0.9.0"]` (pinned) | | API keys | None required | | Path policy | `~/` and system temp dirs (default) | +| Install-time network | npm registry, one-time fetch | +| Runtime network | None | -## Claude Desktop +## Claude Desktop (pinned version, recommended) Add to `claude_desktop_config.json`: @@ -21,12 +30,14 @@ Add to `claude_desktop_config.json`: "mcpServers": { "safe-docx": { "command": "npx", - "args": ["-y", "@usejunior/safe-docx"] + "args": ["-y", "@usejunior/safe-docx@0.9.0"] } } } ``` +Pinning the version prevents unexpected updates. Check the [CHANGELOG](https://github.com/UseJunior/safe-docx/blob/main/CHANGELOG.md) before bumping. + ## Cursor Add to `.cursor/mcp.json` in your project root: @@ -36,14 +47,63 @@ Add to `.cursor/mcp.json` in your project root: "mcpServers": { "safe-docx": { "command": "npx", - "args": ["-y", "@usejunior/safe-docx"] + "args": ["-y", "@usejunior/safe-docx@0.9.0"] + } + } +} +``` + +## Offline / High-Security Install + +For environments where `npx` fetching from npm is unacceptable, install the package manually and invoke the installed binary directly: + +```bash +# Install a specific pinned version globally +npm install -g @usejunior/safe-docx@0.9.0 +``` + +Then configure your MCP client to use the installed binary: + +```json +{ + "mcpServers": { + "safe-docx": { + "command": "safe-docx", + "args": [] } } } ``` +This eliminates the runtime `npx` fetch entirely. The MCP server has zero outbound network calls once installed. + +### Vendored install + +To vendor the package into your project without touching a registry at run time: + +```bash +npm pack @usejunior/safe-docx@0.9.0 +# Inspect the tarball, then: +npm install -g ./usejunior-safe-docx-0.9.0.tgz +``` + +### Build from source + +For maximum auditability: + +```bash +git clone https://github.com/UseJunior/safe-docx.git +cd safe-docx +git checkout v0.9.0 +npm ci +npm run build +npm link packages/safe-docx +``` + ## Notes - **No API keys** — Safe-DOCX runs locally and does not call external services. - **Path policy** — By default, only files under the home directory (`~/`) and system temp directories are accessible. Symlinks must resolve to allowed roots. -- **Node.js required** — `npx` requires Node.js 18+ on the host machine. +- **Install-time vs runtime network** — The default `npx` connector fetches the package from npm on first run. After install, the server has zero outbound network calls. Use the offline install path above if one-time install fetching is unacceptable. +- **No postinstall scripts** — The package declares no `postinstall`, `preinstall`, or `install` hooks. Verify with `npm view @usejunior/safe-docx scripts`. +- **Provenance** — Releases are published with npm provenance, so each published version can be cryptographically traced back to the GitHub Actions build that produced it. diff --git a/skills/docx-editing/SKILL.md b/skills/docx-editing/SKILL.md index 0468f3f..798414c 100644 --- a/skills/docx-editing/SKILL.md +++ b/skills/docx-editing/SKILL.md @@ -8,23 +8,128 @@ description: >- Not for from-scratch document generation. license: MIT compatibility: >- - Works with any agent. Local MCP server requires Node.js >=20 - and runs entirely on the local filesystem. + Works with any MCP-compatible agent. Requires Node.js >=18.0.0 and npm + (for npx) on the host machine. The MCP server runs locally as a stdio + child process. Install-time: npm registry fetch (one-time, cacheable). + Runtime: zero network calls, file access limited to ~/ and system temp. +requires: + binaries: + - node (>=18.0.0) + - npx (bundled with npm) + network: + install_time: npm registry (registry.npmjs.org) — one-time fetch + runtime: none + filesystem: + - ~/ (home directory) + - system temp directories metadata: author: safe-docx - version: "0.1.0" + version: "0.3.0" --- # Editing .docx Files with Safe-DOCX -Safe-DOCX is a local MCP server for surgically editing existing `.docx` files. It preserves formatting, generates tracked-changes redlines, and runs entirely on the local filesystem — no hosted endpoint, no data leaves the machine. +Safe-DOCX is a local MCP server for surgically editing existing `.docx` files. It preserves formatting, generates tracked-changes redlines, and — once installed — runs entirely on the local filesystem with zero network activity. + +## Source Code and Audit + +Safe-DOCX is fully open source (MIT license). Review the complete source before installing: + +- **GitHub**: https://github.com/UseJunior/safe-docx +- **npm registry**: https://www.npmjs.com/package/@usejunior/safe-docx +- **Code coverage**: Published via Codecov on every release +- **Conformance harness**: Automated spec coverage tests run in CI on every commit +- **No postinstall scripts** — verify: `npm view @usejunior/safe-docx scripts` shows no `postinstall` or `install` hooks + +All security claims below are verifiable by reading the source. + +## Runtime Requirements + +Safe-DOCX requires these binaries to be available on the host: + +| Binary | Minimum version | Why | +|--------|-----------------|-----| +| `node` | 18.0.0 | Authoritative version from `packages/safe-docx/package.json` engines field | +| `npx` | Bundled with npm | Used by the recommended MCP connector to launch the server | + +If you prefer not to use `npx`, see **Offline / Pinned Installation** below for alternatives. ## Safety Model -- **Local-only stdio runtime** — the MCP server runs as a child process, never binds a port. +Safe-DOCX's safety model has two distinct phases: **install time** (when the package is fetched) and **runtime** (when the MCP server is running). + +### Install-Time Behavior (network required, one-time) + +- **npm registry fetch** — the recommended connector command `npx -y @usejunior/safe-docx` downloads the package from `registry.npmjs.org` on first run. Subsequent runs use the cached copy unless the cache is cleared. +- **No postinstall scripts** — the package declares no `postinstall`, `preinstall`, or `install` hooks. Verify with `npm view @usejunior/safe-docx scripts`. +- **Provenance** — releases are published with npm provenance (`--provenance`), so you can verify the package was built from the public GitHub repo via GitHub Actions. +- **If you need guaranteed offline install** — pin a specific version and vendor it locally. See the next section. + +### Runtime Behavior (zero network) + +- **Local-only stdio runtime** — the MCP server runs as a child process, never binds a port. Verify: the entry point (`src/server.ts`) uses `StdioServerTransport` with no HTTP listener. ([source](https://github.com/UseJunior/safe-docx/blob/main/packages/safe-docx/src/server.ts)) +- **No outbound network calls** — at runtime, the package makes zero outbound HTTP requests. Verify: `grep -r "fetch\|http\.\|https\.\|net\." packages/safe-docx/src/` returns no matches in application code (test fixtures excluded). - **Path policy** — only files under `~/` (home directory) and system temp directories are accessible. Symlinks must resolve to allowed roots. - **Archive guardrails** — zip bomb detection and hostile payload rejection protect against malformed `.docx` inputs. +## Offline / Pinned Installation + +For high-security environments where `npx` auto-fetch is unacceptable, install the package manually and pin the version: + +```bash +# Option 1: Pin a specific version globally +npm install -g @usejunior/safe-docx@0.9.0 + +# Then configure your MCP client to invoke it by path: +# command: "safe-docx" +# args: [] + +# Option 2: Vendor the package into your project +npm pack @usejunior/safe-docx@0.9.0 +# Inspect the tarball, then install it from disk: +npm install -g ./usejunior-safe-docx-0.9.0.tgz + +# Option 3: Build from source (most auditable) +git clone https://github.com/UseJunior/safe-docx.git +cd safe-docx +git checkout +npm ci +npm run build +npm link packages/safe-docx +``` + +After any of these, your MCP client config becomes: + +```json +{ + "mcpServers": { + "safe-docx": { + "command": "safe-docx", + "args": [] + } + } +} +``` + +Using `command: "safe-docx"` (the installed binary) instead of `command: "npx"` eliminates the install-time network fetch on every invocation. + +### Always pin the version + +Even with `npx`, you can pin the version to prevent unexpected updates: + +```json +{ + "mcpServers": { + "safe-docx": { + "command": "npx", + "args": ["-y", "@usejunior/safe-docx@0.9.0"] + } + } +} +``` + +Before upgrading, review the changelog: https://github.com/UseJunior/safe-docx/blob/main/CHANGELOG.md + ## When to Use This Skill Use Safe-DOCX when you need to: @@ -159,6 +264,16 @@ Call `accept_changes(session_id)` to flatten all tracked changes into a clean do By default, only files under `~/` (home directory) and system temp directories are accessible. Symlinks must resolve to allowed roots. +## Related Skills + +- **Open Agreements** (`open-agreements`) — fill standard legal templates (NDAs, SAFEs, cloud service agreements) and produce signable DOCX files: `clawhub install open-agreements/open-agreements` +- **Outlook Email Management** (`outlook-email-management`) — manage Outlook email with AI agents: `clawhub install stevenobiajulu/outlook-email-management` + ## Connectors For MCP server setup instructions (Claude Desktop, Cursor, Claude Code), see [CONNECTORS.md](./CONNECTORS.md). + +## Feedback + +If this skill helped, star us on GitHub: https://github.com/UseJunior/safe-docx +On ClawHub: `clawhub star usejunior/docx-editing`