@wrongstack/persistence 0.306.0 → 0.306.2

package/dist/file-permissions.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Owner-only file hardening, on both POSIX and Windows.
+ *
+ * WS-045: this lived as a private function inside `secret-vault.ts` and was
+ * therefore reachable only by the config file. Every other secret WrongStack
+ * writes — the HQ `auth.json` (bearer tokens), `runtime.json` (local client
+ * token), the vault `.key` — got `chmod(0o600)` at best, which on Windows is
+ * a no-op for everything except the read-only bit: the file stayed readable by
+ * every other account on the machine. One exported module so a new secret file
+ * has an obvious thing to call.
+ *
+ * ## Why it lives in `@wrongstack/persistence`
+ *
+ * It started in `@wrongstack/core/security`, which put it out of reach of the
+ * one project daemon that needed it most: `@wrongstack/kanban` depends only on
+ * this package, and it cannot depend on core — core already depends on kanban,
+ * so that edge would close a cycle. Every project daemon writes a metadata
+ * file holding its per-process IPC auth token, and every one of them needs the
+ * same owner-only guarantee, so the helper belongs next to `atomicWrite`: a
+ * dependency-free filesystem primitive that all of core, kanban, sage and
+ * tools already import. `@wrongstack/core/security` re-exports it, so existing
+ * callers are unchanged.
+ *
+ * @module file-permissions
+ */
+/** Owner read/write, nothing for group or other. */
+export declare const SECRET_FILE_MODE = 384;
+/** Owner-only directory: enter + list + write. */
+export declare const SECRET_DIR_MODE = 448;
+export interface RestrictPermissionsOptions {
+    warn?: ((msg: string) => void) | undefined;
+    /** Label used in warnings, e.g. `secret-vault` or `hq-auth`. */
+    label?: string | undefined;
+}
+/**
+ * Restrict a file to owner-only access.
+ *
+ * POSIX: `chmod 0600`. Windows: `chmod` cannot express this, so we use
+ * `icacls` to drop inherited ACEs and grant the current user alone.
+ *
+ * Failures are warned, never thrown — a hardening step must not be able to
+ * block the write it protects, and `icacls` is absent in some minimal
+ * environments (containers, WINE, restricted CI images).
+ */
+export declare function restrictFilePermissions(filePath: string, opts?: RestrictPermissionsOptions): Promise<void>;
+/**
+ * `restrictFilePermissions` for a directory: `chmod 0700` on POSIX, the same
+ * icacls treatment (applied recursively to new children via inheritance) on
+ * Windows. Use on the directory that holds secret files so a file created
+ * there by a path we do not control still lands owner-only.
+ */
+export declare function restrictDirPermissions(dirPath: string, opts?: RestrictPermissionsOptions): Promise<void>;
+//# sourceMappingURL=file-permissions.d.ts.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './atomic-write.js';
+export * from './file-permissions.js';
 export * from './project-endpoint.js';
 export * from './socket-path.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -239,6 +239,58 @@ var atomicWrite = defaultPrimitives.atomicWrite;
 var ensureDir = defaultPrimitives.ensureDir;
 var withFileLock = defaultPrimitives.withFileLock;
 
+// src/file-permissions.ts
+import { chmod as chmod2 } from "node:fs/promises";
+var SECRET_FILE_MODE = 384;
+var SECRET_DIR_MODE = 448;
+async function restrictFilePermissions(filePath, opts) {
+  const label = opts?.label ?? "file-permissions";
+  const warn = opts?.warn ?? ((msg) => console.warn(msg));
+  if (process.platform === "win32") {
+    try {
+      const { execFile } = await import("node:child_process");
+      const { promisify } = await import("node:util");
+      const execFileAsync = promisify(execFile);
+      const user = windowsAccountName();
+      if (!user) {
+        warn(
+          `[${label}] Could not determine the current Windows user for ${filePath}; skipping icacls hardening.`
+        );
+        return;
+      }
+      await execFileAsync("icacls", [filePath, "/inheritance:r", "/grant:r", `${user}:(F)`], {
+        windowsHide: true
+      });
+    } catch {
+      warn(
+        `[${label}] Could not restrict permissions on ${filePath} \u2014 it may be readable by other users on this system.`
+      );
+    }
+  } else {
+    try {
+      await chmod2(filePath, SECRET_FILE_MODE);
+    } catch {
+    }
+  }
+}
+async function restrictDirPermissions(dirPath, opts) {
+  if (process.platform === "win32") {
+    await restrictFilePermissions(dirPath, opts);
+    return;
+  }
+  try {
+    await chmod2(dirPath, SECRET_DIR_MODE);
+  } catch {
+  }
+}
+function windowsAccountName() {
+  const username = process.env.USERNAME || process.env.USER;
+  if (!username || username.includes("\0")) return void 0;
+  const domain = process.env.USERDOMAIN;
+  if (domain && !domain.includes("\0")) return `${domain}\\${username}`;
+  return username;
+}
+
 // src/project-endpoint.ts
 import * as fsPromises from "node:fs/promises";
 import * as net from "node:net";
@@ -367,6 +419,8 @@ async function bindProjectEndpoint(options) {
 }
 export {
   PersistenceFsError,
+  SECRET_DIR_MODE,
+  SECRET_FILE_MODE,
   assertUnixSocketPathWithinLimit,
   atomicWrite,
   bindProjectEndpoint,
@@ -374,6 +428,8 @@ export {
   createPersistencePrimitives,
   ensureDir,
   isProjectEndpointLive,
+  restrictDirPermissions,
+  restrictFilePermissions,
   unixSocketPathLimit,
   withFileLock
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/persistence",
-  "version": "0.306.0",
+  "version": "0.306.2",
   "license": "MIT",
   "description": "Dependency-free filesystem persistence primitives shared across WrongStack packages.",
   "repository": {