From c4171af8894a599125c6bd7e473fdf62e19f987e Mon Sep 17 00:00:00 2001
From: phant0um <84820508+phant0um@users.noreply.github.com>
Date: Thu, 5 Nov 2026 14:35:30 -0400
Subject: [PATCH] fix(cli): skip POSIX key file mode check in doctor on Windows
 (#14308)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `paperclipai doctor` checks the local install, including the local
encrypted secrets key file
> - The check reads the POSIX permission bits of the key file and warns
when group or others can read it
> - On Windows, `fs.statSync().mode` is always `0o666` for a writable
file, and `chmod` cannot restrict it
> - So on Windows the check always warns, and the suggested `chmod 600`
has no effect
> - The server secret provider health check has the same check and the
same false positive
> - This pull request skips the POSIX permission-bit check on `win32` in
both places
> - The benefit is that `doctor` and the secret provider health
endpoints on Windows no longer show a permanent false-positive warning

## Linked Issues or Issue Description

Fixes #14255

## What Changed

- `cli/src/checks/secrets-check.ts`: skip the key file permission-bit
check when `process.platform === "win32"`. Linux and macOS behavior does
not change.
- `cli/src/__tests__/secrets.test.ts`: add two tests. One test mocks
`process.platform` as `win32` and expects `pass` for a `0o666` key file.
One test pins the POSIX behavior: a `0o644` key file still gives `warn`
(skipped on Windows runners).
- `server/src/secrets/local-encrypted-provider.ts`: the same `win32`
skip in the local encrypted provider health check. This check feeds `GET
/api/companies/{id}/secret-providers/health`, `POST
/api/secret-provider-configs/{id}/health`, and the `validateConfig`
warnings.
- `server/src/__tests__/secret-provider-registry.test.ts`: add a `win32`
test that expects status `ok` with no warnings for a `0o666` key file.
Mark the existing `0o644` warning test `skipIf(win32)`.

## Verification

- `cd cli && npx vitest run src/__tests__/secrets.test.ts`: 10 of 10
tests pass on macOS (Node 22.22.3).
- Red before the fix: with the fix reverted, 1 failed and 9 passed. The
new Windows test fails with `expected 'warn' to be 'pass'`.
- `cd server && npx vitest run
src/__tests__/secret-provider-registry.test.ts`: 3 of 3 tests pass. Red
before the fix: the new `win32` test failed 2 times with status `warn`.
- Full CLI suite (`cd cli && npx vitest run`): the same 28 tests in
`doctor`, `install-command`, `update-command`, and `worktree` fail on
`master` without this change and with it. My local checkout has no
workspace builds, because I installed with `--ignore-scripts`. This
change adds 2 passing tests and no new failures.
- `cd cli && npx tsc --noEmit`: 233 errors on `master` and 233 with this
change. All errors come from unbuilt workspace packages. No error is in
`cli/src`.
- I did not run the check on a real Windows machine. The Windows test
mocks `process.platform`.

## Risks

- Low risk. The change only removes a warning on Windows. On Windows the
old check always fired, so it gave no signal.
- The repo already skips the same kind of check on `win32`:
`server/src/services/decision-signing.ts` returns early in
`assertOwnedByCurrentUser` and `enforceKeyFilePermissions` for its key
file.
- On Windows, `doctor` no longer checks key file access at all. NTFS
ACLs control access there, and the old check could not read them. An ACL
check is out of scope for this fix.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`, Anthropic), in Claude Code with
tool use (shell, file edit). It reproduced the bug with a failing test,
wrote the fix, and drafted this description. A human reviewed the
change.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes (no
documentation describes this warning)
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 cli/src/__tests__/secrets.test.ts             | 45 +++++++++++++++++++
 cli/src/checks/secrets-check.ts               |  4 +-
 .../secret-provider-registry.test.ts          | 23 +++++++++-
 .../src/secrets/local-encrypted-provider.ts   |  4 +-
 4 files changed, 72 insertions(+), 4 deletions(-)

diff --git a/cli/src/__tests__/secrets.test.ts b/cli/src/__tests__/secrets.test.ts
index 8ae2a77ff5c..cef60632867 100644
--- a/cli/src/__tests__/secrets.test.ts
+++ b/cli/src/__tests__/secrets.test.ts
@@ -1,3 +1,7 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { Agent, CompanySecret } from "@paperclipai/shared";
@@ -262,6 +266,47 @@ describe("secrets CLI helpers", () => {
     expect(result.message).toContain("prod-us-1");
     expect(result.message).toContain("AWS_PROFILE/shared config");
   });
+
+  describe("local encrypted key file permissions", () => {
+    let tempDir: string;
+    let keyFilePath: string;
+
+    beforeEach(() => {
+      delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-secrets-check-"));
+      keyFilePath = path.join(tempDir, "master.key");
+      fs.writeFileSync(keyFilePath, randomBytes(32).toString("base64"), "utf8");
+      process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = keyFilePath;
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it.skipIf(process.platform === "win32")(
+      "warns when the key file is readable by group or others",
+      () => {
+        fs.chmodSync(keyFilePath, 0o644);
+
+        const result = secretsCheck(configWithSecretsProvider("local_encrypted"));
+
+        expect(result.status).toBe("warn");
+        expect(result.message).toContain("key file permissions are 644");
+      },
+    );
+
+    it("does not warn about POSIX permission bits on Windows", () => {
+      fs.chmodSync(keyFilePath, 0o666);
+      vi.spyOn(process, "platform", "get").mockReturnValue("win32");
+
+      const result = secretsCheck(configWithSecretsProvider("local_encrypted"));
+
+      expect(result.status).toBe("pass");
+      expect(result.message).not.toContain("chmod 600");
+      expect(result.repairHint).toBeUndefined();
+    });
+  });
 });
 
 describe("secrets API parity commands", () => {
diff --git a/cli/src/checks/secrets-check.ts b/cli/src/checks/secrets-check.ts
index 73f9c0402c1..6cd64f1d0dc 100644
--- a/cli/src/checks/secrets-check.ts
+++ b/cli/src/checks/secrets-check.ts
@@ -141,9 +141,11 @@ export function secretsCheck(config: PaperclipConfig, configPath?: string): Chec
     };
   }
 
+  // Windows has no POSIX permission bits: stat() reports 0o666 for any writable
+  // file and chmod cannot restrict it, so this check would always warn there.
   const keyMode = fs.statSync(keyFilePath).mode & 0o777;
   const permissionWarning =
-    (keyMode & 0o077) !== 0
+    process.platform !== "win32" && (keyMode & 0o077) !== 0
       ? `; key file permissions are ${keyMode.toString(8)} (run chmod 600 ${keyFilePath})`
       : "";
 
diff --git a/server/src/__tests__/secret-provider-registry.test.ts b/server/src/__tests__/secret-provider-registry.test.ts
index 326fd40682a..8059fe486fc 100644
--- a/server/src/__tests__/secret-provider-registry.test.ts
+++ b/server/src/__tests__/secret-provider-registry.test.ts
@@ -2,7 +2,7 @@ import { randomBytes } from "node:crypto";
 import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { checkSecretProviders, listSecretProviders } from "../secrets/provider-registry.js";
 
 describe("secret provider registry", () => {
@@ -11,6 +11,7 @@ describe("secret provider registry", () => {
   const tmpDirs: string[] = [];
 
   afterEach(() => {
+    vi.restoreAllMocks();
     if (previousKeyFile === undefined) {
       delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
     } else {
@@ -47,7 +48,7 @@ describe("secret provider registry", () => {
     );
   });
 
-  it("warns when the local encrypted key file is readable by group or others", async () => {
+  it.skipIf(process.platform === "win32")("warns when the local encrypted key file is readable by group or others", async () => {
     const dir = path.join(os.tmpdir(), `paperclip-secret-provider-${randomBytes(6).toString("hex")}`);
     tmpDirs.push(dir);
     mkdirSync(dir, { recursive: true });
@@ -67,4 +68,22 @@ describe("secret provider registry", () => {
     expect(local?.warnings?.join("\n")).toContain("chmod 600");
     expect(local?.backupGuidance?.join("\n")).toContain("database");
   });
+
+  it("does not warn about POSIX permission bits on Windows", async () => {
+    const dir = path.join(os.tmpdir(), `paperclip-secret-provider-${randomBytes(6).toString("hex")}`);
+    tmpDirs.push(dir);
+    mkdirSync(dir, { recursive: true });
+    const keyFile = path.join(dir, "master.key");
+    writeFileSync(keyFile, randomBytes(32).toString("base64"), "utf8");
+    chmodSync(keyFile, 0o666);
+    process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = keyFile;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+    vi.spyOn(process, "platform", "get").mockReturnValue("win32");
+
+    const checks = await checkSecretProviders();
+    const local = checks.find((check) => check.provider === "local_encrypted");
+
+    expect(local).toMatchObject({ status: "ok", details: { keyFilePath: keyFile } });
+    expect(local?.warnings ?? []).toEqual([]);
+  });
 });
diff --git a/server/src/secrets/local-encrypted-provider.ts b/server/src/secrets/local-encrypted-provider.ts
index bc4820a3d38..ce7f4572194 100644
--- a/server/src/secrets/local-encrypted-provider.ts
+++ b/server/src/secrets/local-encrypted-provider.ts
@@ -199,8 +199,10 @@ async function inspectLocalEncryptedHealth(): Promise<SecretProviderHealthCheck>
     };
   }
 
+  // Windows has no POSIX permission bits: stat() reports 0o666 for any writable
+  // file and chmod cannot restrict it, so this check would always warn there.
   const warnings =
-    mode !== null && (mode & 0o077) !== 0
+    process.platform !== "win32" && mode !== null && (mode & 0o077) !== 0
       ? [`Secrets key file permissions are ${mode.toString(8)}; run chmod 600 ${keyPath}`]
       : [];
   return {