ccu-mcp

ccu-mcp follows semantic versioning and provides an upgrade path rather than maintaining parallel older versions: fixes land in the current release line, and users upgrade with "npm install -g ccu-mcp@latest" or by bumping the pinned version. Older releases remain permanently available as signed git tags and as npm versions. CHANGELOG.md documents every release, and any release with a behaviour change carries an explicit "read before upgrading" section describing what changed and what to do about it — see v1.9.1. The supported-version table is in SECURITY.md.

https://github.com/claymore666/ccu-mcp/issues

No vulnerabilities have been reported or resolved in the last 12 months; the repository's security-advisory list is empty. The crediting policy exists and is published in advance: SECURITY.md states that reports are credited in the advisory and in CHANGELOG.md unless the reporter asks otherwise. https://github.com/claymore666/ccu-mcp/blob/dev/SECURITY.md#what-to-expect

A documented response process with explicit stage targets — acknowledgement within 14 days, initial assessment within 30 days, and a fix as fast as severity warrants with a date given once assessment completes — presented honestly as targets for a single-maintainer project rather than as an SLA. Private reporting runs through GitHub Security Advisories. https://github.com/claymore666/ccu-mcp/blob/dev/SECURITY.md#what-to-expect

The identified style guide is the Google TypeScript Style Guide, with two documented deviations: 120-column lines rather than 80, and double quotes. Contributions are required to comply. https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#code-style

"npm run lint" runs oxlint (MIT, FLOSS) over src, test, scripts and fuzz before tsc, and CI runs the same command in the required build-and-test check — so a violation fails the build rather than waiting for review. The ruleset is oxlint's correctness, suspicious and perf categories, all as errors, pinned in .oxlintrc.json in the repository. Every exception is listed there with the reason it is off; per-line exceptions use an oxlint-disable-next-line comment stating why. The gate was mutation-tested before being enabled — deliberately planted no-eval and no-unused-vars violations to confirm it exits non-zero, then confirmed it exits zero once reverted. oxlint is used rather than typescript-eslint because typescript-eslint's peer range is >=4.8.4 <6.1.0 and this project builds on TypeScript 7; no release of it supports the compiler in use.

No native binaries are produced. ccu-mcp is TypeScript compiled to JavaScript by tsc and executed by Node.js; there is no C/C++ compiler or linker in the build, so CC/CFLAGS/CXX/CXXFLAGS/LDFLAGS have nothing to apply to. There is also no native addon or FFI dependency.

tsconfig.json sets sourceMap: true, declaration: true and declarationMap: true, and nothing in the build strips or minifies. The published npm package ships dist/ whole, so .js.map and .d.ts.map reach consumers and a stack trace from an installed copy maps back to the TypeScript source. The build additionally stamps dist/build-info.json with the commit it was built from, surfaced at runtime by the get_system_info tool.

The build is a single tsc invocation over the whole program (include: src/**/*), followed by one script that stamps build metadata. TypeScript resolves the complete module graph itself and there is no per-directory or recursive make-style build, so no subdirectory is built in isolation and cross-directory dependency information cannot be stale.

Verified empirically, not assumed: building, deleting dist/ entirely, and building again from the same source produces byte-identical output — the SHA-256 over all emitted .js and .d.ts files matched exactly across both runs. The build has no private inputs and dependencies are pinned by package-lock.json ("npm ci"). The only file that varies is dist/build-info.json, which records the git commit and build timestamp on purpose so a running server can report which checkout it came from; it is generated metadata, not compiled output, and is a pure function of the commit apart from the timestamp.

Installed and uninstalled with the standard package manager for the language: "npm install -g ccu-mcp" / "npm uninstall -g ccu-mcp", or run without installing via "npx ccu-mcp". A Docker image is also provided, with a docker-compose.yml in the repository, so "docker compose up" / "docker compose down" works as an alternative. README.md documents both routes.

There is no POSIX-style installation step to parameterise. npm decides the install location itself, honouring its own standard configuration ("npm config set prefix", --prefix, NPM_CONFIG_PREFIX); DESTDIR has no meaning for a package manager install, and the project neither writes files outside npm's control nor ships a "make install".

"git clone && npm ci && npm run lint && npm test" — three standard commands, no bespoke tooling, and the test environment is included: the unit and end-to-end suites run against a mocked CCU and need no hardware at all. The only prerequisite is Node.js >= 24, declared in package.json engines. Documented step by step at https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#development-setup , including the live-integration suites, which are gated on CCU_HOST and skipped unless a real CCU is deliberately supplied.

Dependencies are declared in package.json in the standard computer-processable npm format, with exact resolution pinned in package-lock.json. Production dependencies are deliberately few — three: @modelcontextprotocol/sdk, undici and zod. https://github.com/claymore666/ccu-mcp/blob/dev/package.json

Three independent layers, all automated. (1) Dependabot opens PRs for outdated dependencies, with auto-merge configured. (2) .github/workflows/audit.yml runs "npm audit --omit=dev" daily against production dependencies for high/critical advisories and maintains a single labelled tracking issue; it is green whenever the audit ran and red only when it could not run. (3) release-gate.yml's release-audit job is a required check on every pull request into "main", so no release can go out with an unresolved high or critical advisory in production dependencies. A dependency-review workflow also runs on pull requests. Scanning is deliberately kept out of the required per-commit check, because an advisory database changes with no diff and would make that check non-hermetic.

Every external component is a normal npm dependency resolved from the registry at install time. There are no vendored, bundled or forked convenience copies anywhere in the tree, and no source of a third-party library is checked in. Updating any component is "npm update" or a version bump in package.json, which is exactly what Dependabot automates.

Verified rather than assumed: the source was swept for the deprecated Node.js APIs (new Buffer(), url.parse(), util.isArray(), crypto.createCipher(), fs.exists(), domain) and uses none of them. The project targets Node.js >= 24 and uses current APIs throughout — node:crypto with timingSafeEqual/scryptSync, node:fs/promises, WHATWG URL, and undici's fetch. "tsc --noEmit" runs over both src and test in CI, so a TypeScript-visible deprecation surfaces at build time.

The build-and-test job in .github/workflows/ci.yml runs on every push and every pull request to both long-lived branches, and is a required status check on "dev" and on "main". It runs lint, type check over src and test, the full unit and end-to-end suites, coverage measurement, the coverage-ratchet self-test and the coverage ratchet itself, and reports success or failure per run in the GitHub Checks UI — so a pull request cannot merge without a visible pass. Currently 469 passing tests.

Measured from the git history rather than estimated: of the commits with a "fix:" subject in the last six months, roughly 72% touched files under test/ in the same commit — comfortably above the 50% threshold. The remainder are dependency bumps and documentation-only corrections, which have no behavioural regression to pin. The policy behind the number is written down and mandatory: CONTRIBUTING.md states that a bug fix must include a test that fails before the fix and passes after it, and that a fix without one is not considered complete. Recent examples: test/unit/prototype-key-handling.test.ts (v1.9.1) and the regression block in test/unit/utils-properties.test.ts.

86.05% statements, enforced globally by vitest.config.ts and per-directory by .github/coverage-baseline.txt

CONTRIBUTING.md contains a written, mandatory test policy: "Any pull request that adds or changes functionality must add or update tests covering it. This is not negotiable for major new functionality: a new tool, a new transport, a new configuration surface, or a change in how an existing tool behaves all require tests in the same PR." Documentation-only and formatting-only changes are the sole exemption. It is backed mechanically: coverage thresholds are enforced globally by vitest and per directory by scripts/coverage-ratchet.mjs in the required CI check, so a change that adds untested code fails the build even when every existing test passes. https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#test-policy

https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#test-policy

Maximally strict where it is practical. TypeScript strict is on with forceConsistentCasingInFileNames, and type checking covers the test sources as well as src — which "npm test" alone does not do. oxlint runs three rule categories as errors rather than warnings. The stricter categories oxlint also offers (pedantic, restriction) are deliberately not enabled: they include rules like no-optional-chaining and no-async-await that would fight the language rather than find defects, and turning them on would mean mass-suppressing them, which is worse than not claiming them.

Secure design principles are applied deliberately and documented criterion-by-criterion at https://github.com/claymore666/ccu-mcp/blob/dev/docs/assurance-case.md , which maps each Saltzer and Schroeder principle to the mechanism implementing it. Concretely: FAIL-SAFE DEFAULTS — CORS is default-deny with an allowlisted origin reflected exactly and never as a wildcard, DNS-rebinding protection is unconditional, the HTTP transport requires a bearer token, and a malformed safety-gate variable (CCU_PROFILE_PROTECTED=yes) is a hard startup error rather than a silently unprotected CCU. COMPLETE MEDIATION — every tool call passes through the same wrapper: zod validation, then the write gate, then the rate limiter; there is no code path to the CCU that bypasses them. LEAST PRIVILEGE — the documented recommendation is a dedicated USER-level CCU account, and the container runs as non-root. SEPARATION OF PRIVILEGE — writing to a protected CCU requires both configuration and an explicit per-session confirmation, with run_script and delete_system_variable requiring it on every call. ECONOMY OF MECHANISM — one process, no database, three production dependencies. The one known deviation, CCU TLS verification being off by default, is stated openly in the same document rather than argued around.

No algorithm or mode with a known serious weakness is used by default. SHA-1 appears nowhere; digests are SHA-256. CBC-mode concerns do not arise, since cipher-suite selection is left entirely to Node/OpenSSL under a TLS 1.2 minimum, where AEAD suites (AES-GCM, ChaCha20-Poly1305) are preferred. Password-equivalent material is handled with scrypt, a deliberately slow salted KDF, rather than any fast hash.

The project implements no cryptography of its own; it uses Node.js/OpenSSL primitives, which support multiple algorithms and negotiate them. TLS to the CCU negotiates from OpenSSL's full modern cipher suite (AES-GCM, ChaCha20-Poly1305; SHA-2 family), and no cipher list, secureProtocol or version is pinned in this project's code, so the platform's algorithm set applies and moves with it. Where the project selects a primitive itself the choice is isolated to one call site and replaceable without touching callers: scrypt for the credential fingerprint (src/ccu/session.ts) and SHA-256 for bearer-token digests and TLS fingerprint pinning.

No credential or key is compiled in or stored in a configuration file mixed with other settings. CCU passwords, MCP_AUTH_TOKEN, TLS certificate/key paths and the CA PEM path all come from environment variables, typically supplied through a .env file, a Docker environment block, or a systemd unit — files separate from code, from logs and from the caches. Changing any of them requires only a restart, never a rebuild: the package ships compiled JavaScript and reads configuration at process start. Bearer tokens additionally support live rotation with an overlap window (MCP_AUTH_TOKEN_PREVIOUS, MCP_AUTH_TOKEN_GRACE_HOURS) so a key can be replaced without dropping clients. .env is gitignored, and .env.example documents every variable without values.

TLS 1.2 is the floor and TLS 1.3 is used where the peer supports it. The project sets no minVersion, maxVersion, secureProtocol or cipher list anywhere in src/, so Node.js's defaults apply unmodified — tls.DEFAULT_MIN_VERSION is TLSv1.2 on the supported runtime (Node >= 24), meaning SSLv3, TLS 1.0 and TLS 1.1 cannot be negotiated at all. Verified against the runtime rather than assumed.

https://registry.npmjs.org/-/npm/v1/attestations/ccu-mcp@1.9.1 — published via npm trusted publishing (OIDC) from GitHub Actions; SLSA provenance, predicateType https://slsa.dev/provenance/v1

Tags are SSH-signed; GitHub reports v1.9.1 as verified: true

Every tool input is declared as a zod schema — an allowlist of shape, type, enum and range — and the MCP SDK rejects anything that does not match before a handler runs; there is no denylist anywhere. This matters more than usual here because the caller is a language model whose arguments may be derived from device or room names an attacker could have written into the CCU, so tool arguments are treated as untrusted regardless of source. Beyond schema validation: configuration values are parsed strictly and fail closed (CCU_PROD_PROTECTED=yes throws rather than reading as false); HM Script fragments are escaped by escapeHmScript(), whose correctness is checked by property tests against an independent unescape oracle and by a nightly coverage-guided fuzzer; caller-supplied object keys are written with Object.fromEntries and read behind Object.hasOwn, so proto cannot reach Object.prototype; and bearer-token parsing uses a linear pattern after a polynomial one was found and removed.

Applied at the transport, resource and runtime layers. TRANSPORT: CORS is default-deny and an allowlisted origin is reflected exactly rather than as a wildcard; DNS-rebinding protection is enabled unconditionally and validates the Host header against an allowlist; bearer tokens are compared as fixed-width SHA-256 digests through timingSafeEqual; WWW-Authenticate is sent on 401; the health endpoint answers liveness only before authentication so it cannot be used to probe CCU state. RESOURCE: a token-bucket rate limiter with a bounded queue, a bounded session map with idle reaping, and a retry budget that re-acquires a token per attempt so a timeout storm cannot double the request rate. RUNTIME: the Docker image runs as a dedicated non-root user; the persisted session cache is written 0600; the credential fingerprint is derived with scrypt and a random salt rather than a fast hash; fail2ban filter and jail definitions are shipped for HTTP deployments. eval is absent from the codebase and now mechanically prohibited by the lint gate.

An assurance case covering the required elements: a top-level claim with its bounding assumptions stated up front, an asset list, four explicitly drawn trust boundaries, five security requirements each with an argument and named file/test evidence plus a residual-risk note, a Saltzer and Schroeder principle table including its one known violation, and a table of implementation weakness classes countered (injection, prototype pollution, broken authentication, sensitive data exposure, improper certificate validation, ReDoS, path traversal, resource exhaustion, vulnerable dependencies). https://github.com/claymore666/ccu-mcp/blob/dev/docs/assurance-case.md

CodeQL is enabled via GitHub default setup (state: configured, default query suite) over javascript-typescript and actions; its default suite includes security queries.

The project produces no software written in a memory-unsafe language. ccu-mcp is TypeScript running on Node.js, with no C/C++ source, no native addon and no FFI dependency, so there is no buffer-overwrite class of defect for a memory-safety tool to detect. Dynamic analysis is nevertheless applied for other defect classes: nightly coverage-guided fuzzing with Jazzer.js against a seeded corpus, plus property-based testing with fast-check on every commit.