@quark-hq/quark-security 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Acko Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/fs.d.ts

@@ -0,0 +1,18 @@
+import fs from "fs";
+export declare function existsSyncSafe(root: string, candidate: string): boolean;
+export declare function mkdirSyncSafe(root: string, candidate: string, options?: fs.MakeDirectoryOptions): void;
+export declare function readFileSyncSafe(root: string, candidate: string, encoding?: BufferEncoding): string;
+type WriteFileSyncOptions = {
+    encoding?: BufferEncoding;
+    mode?: number;
+    flag?: string;
+};
+export declare function writeFileSyncSafe(root: string, candidate: string, data: string | NodeJS.ArrayBufferView, options?: BufferEncoding | WriteFileSyncOptions): void;
+export declare function rmSyncSafe(root: string, candidate: string, options?: fs.RmOptions): void;
+export declare function readFileSafe(root: string, candidate: string): Promise<string>;
+export declare function readdirWithFileTypesSafe(root: string, candidate: string): Promise<fs.Dirent[]>;
+export declare function writeFileSafe(root: string, candidate: string, data: string): Promise<void>;
+export declare function unlinkSafe(root: string, candidate: string): Promise<void>;
+export declare function rmSafe(root: string, candidate: string, options?: fs.RmOptions): Promise<void>;
+export {};
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AASpB,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAGvE;AAED,wBAAgB,aAAa,CACzB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,EAAE,CAAC,oBAAoB,GAClC,IAAI,CAGN;AAED,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,cAAuB,GAClC,MAAM,CAGR;AAED,KAAK,oBAAoB,GAAG;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,EACrC,OAAO,CAAC,EAAE,cAAc,GAAG,oBAAoB,GAChD,IAAI,CAON;AAED,wBAAgB,UAAU,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,EAAE,CAAC,SAAS,GACvB,IAAI,CAGN;AAGD,wBAAsB,YAAY,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAsB,wBAAwB,CAC1C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAGtB;AAED,wBAAsB,aAAa,CAC/B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,UAAU,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,MAAM,CACxB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,EAAE,CAAC,SAAS,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/fs.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.existsSyncSafe = existsSyncSafe;
+exports.mkdirSyncSafe = mkdirSyncSafe;
+exports.readFileSyncSafe = readFileSyncSafe;
+exports.writeFileSyncSafe = writeFileSyncSafe;
+exports.rmSyncSafe = rmSyncSafe;
+exports.readFileSafe = readFileSafe;
+exports.readdirWithFileTypesSafe = readdirWithFileTypesSafe;
+exports.writeFileSafe = writeFileSafe;
+exports.unlinkSafe = unlinkSafe;
+exports.rmSafe = rmSafe;
+const fs_1 = __importDefault(require("fs"));
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const paths_1 = require("./paths");
+function toSafePath(root, candidate) {
+    return (0, paths_1.assertPathInsideRoot)(root, path_1.default.resolve(candidate));
+}
+function existsSyncSafe(root, candidate) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    return fs_1.default.existsSync(toSafePath(root, candidate));
+}
+function mkdirSyncSafe(root, candidate, options) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    fs_1.default.mkdirSync(toSafePath(root, candidate), options);
+}
+function readFileSyncSafe(root, candidate, encoding = "utf8") {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    return fs_1.default.readFileSync(toSafePath(root, candidate), encoding);
+}
+function writeFileSyncSafe(root, candidate, data, options) {
+    const safe = toSafePath(root, candidate);
+    const resolved = typeof options === "string" || options === undefined
+        ? { encoding: options ?? "utf8" }
+        : options;
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    fs_1.default.writeFileSync(safe, data, resolved);
+}
+function rmSyncSafe(root, candidate, options) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    fs_1.default.rmSync(toSafePath(root, candidate), options);
+}
+async function readFileSafe(root, candidate) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    return promises_1.default.readFile(toSafePath(root, candidate), "utf8");
+}
+async function readdirWithFileTypesSafe(root, candidate) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    return promises_1.default.readdir(toSafePath(root, candidate), { withFileTypes: true });
+}
+async function writeFileSafe(root, candidate, data) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    await promises_1.default.writeFile(toSafePath(root, candidate), data, "utf8");
+}
+async function unlinkSafe(root, candidate) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    await promises_1.default.unlink(toSafePath(root, candidate));
+}
+async function rmSafe(root, candidate, options) {
+    // bearer:disable javascript_lang_non_literal_fs_filename
+    await promises_1.default.rm(toSafePath(root, candidate), options);
+}

package/dist/git.d.ts

@@ -0,0 +1,7 @@
+export declare function assertSafeGitBranch(branch: string, label: string): void;
+export declare function assertSafeGitRef(ref: string, label: string): void;
+/**
+ * Path used in `git show <ref>:<path>` (repo-relative, POSIX-style segments).
+ */
+export declare function assertSafeRepoRelativePathForGitShow(relativePath: string, label: string): void;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAuCA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAUvE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAUjE;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAChD,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACd,IAAI,CAgBN"}

package/dist/git.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeGitBranch = assertSafeGitBranch;
+exports.assertSafeGitRef = assertSafeGitRef;
+exports.assertSafeRepoRelativePathForGitShow = assertSafeRepoRelativePathForGitShow;
+const MAX_REF_LEN = 256;
+/** Git branch / simple ref names (e.g. main, feature/foo). */
+const BRANCH_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9._/-]*[a-zA-Z0-9])?$/;
+/**
+ * Tags, full SHAs, short SHAs, refs like refs/tags/v1.0.0.
+ * Conservative ASCII set; rejects shell metacharacters and path tricks.
+ */
+const GIT_REF_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9._^~/@+-]*[a-zA-Z0-9])?$/;
+function hasForbiddenSequences(s) {
+    return (s.includes("..") ||
+        s.includes("\n") ||
+        s.includes("\r") ||
+        s.includes("\0") ||
+        s.includes("`") ||
+        s.includes("$") ||
+        s.includes(";") ||
+        s.includes("|") ||
+        s.includes("&") ||
+        s.includes("(") ||
+        s.includes(")") ||
+        s.includes("<") ||
+        s.includes(">") ||
+        s.includes("*") ||
+        s.includes("?") ||
+        s.includes("[") ||
+        s.includes("]") ||
+        s.includes("\\") ||
+        s.includes("\"") ||
+        s.includes("'") ||
+        s.includes(" ") ||
+        s.includes(":") // ref:path separator; ref must not contain ':'
+    );
+}
+function assertSafeGitBranch(branch, label) {
+    if (!branch || branch.length > MAX_REF_LEN) {
+        throw new Error(`Invalid ${label}: length or empty`);
+    }
+    if (hasForbiddenSequences(branch)) {
+        throw new Error(`Invalid ${label}: forbidden characters`);
+    }
+    if (!BRANCH_PATTERN.test(branch)) {
+        throw new Error(`Invalid ${label}: format`);
+    }
+}
+function assertSafeGitRef(ref, label) {
+    if (!ref || ref.length > MAX_REF_LEN) {
+        throw new Error(`Invalid ${label}: length or empty`);
+    }
+    if (hasForbiddenSequences(ref)) {
+        throw new Error(`Invalid ${label}: forbidden characters`);
+    }
+    if (!GIT_REF_PATTERN.test(ref)) {
+        throw new Error(`Invalid ${label}: format`);
+    }
+}
+/**
+ * Path used in `git show <ref>:<path>` (repo-relative, POSIX-style segments).
+ */
+function assertSafeRepoRelativePathForGitShow(relativePath, label) {
+    if (!relativePath || relativePath.length > 4096) {
+        throw new Error(`Invalid ${label}: length or empty`);
+    }
+    if (relativePath.startsWith("/") || relativePath.startsWith("\\")) {
+        throw new Error(`Invalid ${label}: must be relative`);
+    }
+    if (relativePath.includes("\0") || relativePath.includes(":")) {
+        throw new Error(`Invalid ${label}: forbidden characters`);
+    }
+    const parts = relativePath.split(/[/\\]/);
+    for (const p of parts) {
+        if (p === "..") {
+            throw new Error(`Invalid ${label}: must not contain '..'`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { assertPathInsideRoot, assertSafePathSegment, resolveRelativeNameUnderRoot, resolveUnderWorkspaceRoot, } from "./paths";
+export { existsSyncSafe, mkdirSyncSafe, readFileSafe, readFileSyncSafe, readdirWithFileTypesSafe, rmSafe, rmSyncSafe, unlinkSafe, writeFileSafe, writeFileSyncSafe, } from "./fs";
+export { validateNpmPackageName, assertValidNpmPackageName, type NpmNameValidation, } from "./npm";
+export { assertSafeGitBranch, assertSafeGitRef, assertSafeRepoRelativePathForGitShow, } from "./git";
+export { stripUrlCredentials, formatErrorMessage, shouldLogErrorStack, } from "./logging";
+export { spawnSyncSafe, assertSpawnOk, assertSafeExecutableRef, assertSafeSpawnArg, assertSafeSpawnArgs, type SpawnSyncSafeOptions, } from "./spawn";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,oBAAoB,EACpB,qBAAqB,EACrB,4BAA4B,EAC5B,yBAAyB,GAC5B,MAAM,SAAS,CAAC;AACjB,OAAO,EACH,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,MAAM,EACN,UAAU,EACV,UAAU,EACV,aAAa,EACb,iBAAiB,GACpB,MAAM,MAAM,CAAC;AACd,OAAO,EACH,sBAAsB,EACtB,yBAAyB,EACzB,KAAK,iBAAiB,GACzB,MAAM,OAAO,CAAC;AACf,OAAO,EACH,mBAAmB,EACnB,gBAAgB,EAChB,oCAAoC,GACvC,MAAM,OAAO,CAAC;AACf,OAAO,EACH,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACH,aAAa,EACb,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,oBAAoB,GAC5B,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeSpawnArgs = exports.assertSafeSpawnArg = exports.assertSafeExecutableRef = exports.assertSpawnOk = exports.spawnSyncSafe = exports.shouldLogErrorStack = exports.formatErrorMessage = exports.stripUrlCredentials = exports.assertSafeRepoRelativePathForGitShow = exports.assertSafeGitRef = exports.assertSafeGitBranch = exports.assertValidNpmPackageName = exports.validateNpmPackageName = exports.writeFileSyncSafe = exports.writeFileSafe = exports.unlinkSafe = exports.rmSyncSafe = exports.rmSafe = exports.readdirWithFileTypesSafe = exports.readFileSyncSafe = exports.readFileSafe = exports.mkdirSyncSafe = exports.existsSyncSafe = exports.resolveUnderWorkspaceRoot = exports.resolveRelativeNameUnderRoot = exports.assertSafePathSegment = exports.assertPathInsideRoot = void 0;
+var paths_1 = require("./paths");
+Object.defineProperty(exports, "assertPathInsideRoot", { enumerable: true, get: function () { return paths_1.assertPathInsideRoot; } });
+Object.defineProperty(exports, "assertSafePathSegment", { enumerable: true, get: function () { return paths_1.assertSafePathSegment; } });
+Object.defineProperty(exports, "resolveRelativeNameUnderRoot", { enumerable: true, get: function () { return paths_1.resolveRelativeNameUnderRoot; } });
+Object.defineProperty(exports, "resolveUnderWorkspaceRoot", { enumerable: true, get: function () { return paths_1.resolveUnderWorkspaceRoot; } });
+var fs_1 = require("./fs");
+Object.defineProperty(exports, "existsSyncSafe", { enumerable: true, get: function () { return fs_1.existsSyncSafe; } });
+Object.defineProperty(exports, "mkdirSyncSafe", { enumerable: true, get: function () { return fs_1.mkdirSyncSafe; } });
+Object.defineProperty(exports, "readFileSafe", { enumerable: true, get: function () { return fs_1.readFileSafe; } });
+Object.defineProperty(exports, "readFileSyncSafe", { enumerable: true, get: function () { return fs_1.readFileSyncSafe; } });
+Object.defineProperty(exports, "readdirWithFileTypesSafe", { enumerable: true, get: function () { return fs_1.readdirWithFileTypesSafe; } });
+Object.defineProperty(exports, "rmSafe", { enumerable: true, get: function () { return fs_1.rmSafe; } });
+Object.defineProperty(exports, "rmSyncSafe", { enumerable: true, get: function () { return fs_1.rmSyncSafe; } });
+Object.defineProperty(exports, "unlinkSafe", { enumerable: true, get: function () { return fs_1.unlinkSafe; } });
+Object.defineProperty(exports, "writeFileSafe", { enumerable: true, get: function () { return fs_1.writeFileSafe; } });
+Object.defineProperty(exports, "writeFileSyncSafe", { enumerable: true, get: function () { return fs_1.writeFileSyncSafe; } });
+var npm_1 = require("./npm");
+Object.defineProperty(exports, "validateNpmPackageName", { enumerable: true, get: function () { return npm_1.validateNpmPackageName; } });
+Object.defineProperty(exports, "assertValidNpmPackageName", { enumerable: true, get: function () { return npm_1.assertValidNpmPackageName; } });
+var git_1 = require("./git");
+Object.defineProperty(exports, "assertSafeGitBranch", { enumerable: true, get: function () { return git_1.assertSafeGitBranch; } });
+Object.defineProperty(exports, "assertSafeGitRef", { enumerable: true, get: function () { return git_1.assertSafeGitRef; } });
+Object.defineProperty(exports, "assertSafeRepoRelativePathForGitShow", { enumerable: true, get: function () { return git_1.assertSafeRepoRelativePathForGitShow; } });
+var logging_1 = require("./logging");
+Object.defineProperty(exports, "stripUrlCredentials", { enumerable: true, get: function () { return logging_1.stripUrlCredentials; } });
+Object.defineProperty(exports, "formatErrorMessage", { enumerable: true, get: function () { return logging_1.formatErrorMessage; } });
+Object.defineProperty(exports, "shouldLogErrorStack", { enumerable: true, get: function () { return logging_1.shouldLogErrorStack; } });
+var spawn_1 = require("./spawn");
+Object.defineProperty(exports, "spawnSyncSafe", { enumerable: true, get: function () { return spawn_1.spawnSyncSafe; } });
+Object.defineProperty(exports, "assertSpawnOk", { enumerable: true, get: function () { return spawn_1.assertSpawnOk; } });
+Object.defineProperty(exports, "assertSafeExecutableRef", { enumerable: true, get: function () { return spawn_1.assertSafeExecutableRef; } });
+Object.defineProperty(exports, "assertSafeSpawnArg", { enumerable: true, get: function () { return spawn_1.assertSafeSpawnArg; } });
+Object.defineProperty(exports, "assertSafeSpawnArgs", { enumerable: true, get: function () { return spawn_1.assertSafeSpawnArgs; } });

package/dist/logging.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Removes userinfo from URLs so registry URLs with embedded credentials are not logged.
+ */
+export declare function stripUrlCredentials(url: string): string;
+/**
+ * Safe one-line message for console (no stack unless debug).
+ */
+export declare function formatErrorMessage(error: unknown): string;
+export declare function shouldLogErrorStack(): boolean;
+//# sourceMappingURL=logging.d.ts.map

package/dist/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASvD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzD;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAM7C"}

package/dist/logging.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripUrlCredentials = stripUrlCredentials;
+exports.formatErrorMessage = formatErrorMessage;
+exports.shouldLogErrorStack = shouldLogErrorStack;
+/**
+ * Removes userinfo from URLs so registry URLs with embedded credentials are not logged.
+ */
+function stripUrlCredentials(url) {
+    try {
+        const u = new URL(url);
+        u.username = "";
+        u.password = "";
+        return u.toString();
+    }
+    catch {
+        return url.replace(/\/\/[^@/]+@/g, "//***@");
+    }
+}
+/**
+ * Safe one-line message for console (no stack unless debug).
+ */
+function formatErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function shouldLogErrorStack() {
+    return (process.env.DEBUG === "1" ||
+        process.env.DEBUG === "true" ||
+        process.env.NODE_ENV === "development");
+}

package/dist/npm.d.ts

@@ -0,0 +1,10 @@
+export interface NpmNameValidation {
+    valid: boolean;
+    reason: string;
+}
+/**
+ * Validates npm-style package or folder names (aligned with npm package name rules used in init).
+ */
+export declare function validateNpmPackageName(name: string): NpmNameValidation;
+export declare function assertValidNpmPackageName(name: string, label: string): void;
+//# sourceMappingURL=npm.d.ts.map

package/dist/npm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm.d.ts","sourceRoot":"","sources":["../src/npm.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAsBtE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAK3E"}

package/dist/npm.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateNpmPackageName = validateNpmPackageName;
+exports.assertValidNpmPackageName = assertValidNpmPackageName;
+/**
+ * Validates npm-style package or folder names (aligned with npm package name rules used in init).
+ */
+function validateNpmPackageName(name) {
+    const nameRegex = /^(?:@[\w-]+\/)?[\w.-]+$/;
+    if (!nameRegex.test(name)) {
+        return {
+            valid: false,
+            reason: "The name must be a valid npm package name (alphanumeric, dashes, dots, optional @scope/).",
+        };
+    }
+    if (name.trim().length === 0 ||
+        name.includes(" ") ||
+        name.toLowerCase() !== name ||
+        name.startsWith(".") ||
+        name.startsWith("_")) {
+        return {
+            valid: false,
+            reason: "The name contains invalid characters or formatting.",
+        };
+    }
+    return { valid: true, reason: "" };
+}
+function assertValidNpmPackageName(name, label) {
+    const r = validateNpmPackageName(name);
+    if (!r.valid) {
+        throw new Error(`${label}: ${r.reason}`);
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves `candidate` and throws if it is not under `root` (after normalization).
+ * Prevents path traversal via `..` or symlinks escaping the root when combined with realpath callers.
+ */
+export declare function assertPathInsideRoot(root: string, candidate: string): string;
+/**
+ * Ensures a path segment used as a single folder/package name under cwd cannot escape upward.
+ */
+/**
+ * Resolves a single path segment (e.g. package or project name) under root and rejects traversal.
+ */
+export declare function resolveRelativeNameUnderRoot(root: string, name: string): string;
+/**
+ * Resolves a workspace-relative directory (e.g. Nx `project.data.root` like `packages/foo` or `.`)
+ * under `workspaceRoot` and rejects traversal outside the workspace.
+ */
+export declare function resolveUnderWorkspaceRoot(workspaceRoot: string, relativePath: string): string;
+export declare function assertSafePathSegment(segment: string, label: string): void;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAY5E;AAED;;GAEG;AACH;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACrC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACrB,MAAM,CAeR;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAc1E"}

package/dist/paths.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertPathInsideRoot = assertPathInsideRoot;
+exports.resolveRelativeNameUnderRoot = resolveRelativeNameUnderRoot;
+exports.resolveUnderWorkspaceRoot = resolveUnderWorkspaceRoot;
+exports.assertSafePathSegment = assertSafePathSegment;
+const path_1 = __importDefault(require("path"));
+/**
+ * Resolves `candidate` and throws if it is not under `root` (after normalization).
+ * Prevents path traversal via `..` or symlinks escaping the root when combined with realpath callers.
+ */
+function assertPathInsideRoot(root, candidate) {
+    // bearer:disable javascript_lang_path_traversal
+    const resolvedRoot = path_1.default.resolve(root);
+    // bearer:disable javascript_lang_path_traversal
+    const resolved = path_1.default.resolve(candidate);
+    const rel = path_1.default.relative(resolvedRoot, resolved);
+    if (rel.startsWith("..") || path_1.default.isAbsolute(rel)) {
+        throw new Error(`Path is outside allowed root: ${candidate}`);
+    }
+    return resolved;
+}
+/**
+ * Ensures a path segment used as a single folder/package name under cwd cannot escape upward.
+ */
+/**
+ * Resolves a single path segment (e.g. package or project name) under root and rejects traversal.
+ */
+function resolveRelativeNameUnderRoot(root, name) {
+    assertSafePathSegment(name, "path");
+    // bearer:disable javascript_lang_path_traversal
+    const resolved = path_1.default.resolve(root, name);
+    return assertPathInsideRoot(root, resolved);
+}
+/**
+ * Resolves a workspace-relative directory (e.g. Nx `project.data.root` like `packages/foo` or `.`)
+ * under `workspaceRoot` and rejects traversal outside the workspace.
+ */
+function resolveUnderWorkspaceRoot(workspaceRoot, relativePath) {
+    if (typeof relativePath !== "string" || relativePath.includes("\0")) {
+        throw new Error("Invalid relative path");
+    }
+    const trimmed = relativePath.trim();
+    if (trimmed === "" || trimmed === ".") {
+        return assertPathInsideRoot(workspaceRoot, path_1.default.resolve(workspaceRoot));
+    }
+    const normalized = path_1.default.normalize(trimmed);
+    if (normalized.split(/[/\\]/).includes("..")) {
+        throw new Error("Relative path must not contain '..'");
+    }
+    // bearer:disable javascript_lang_path_traversal
+    const joined = path_1.default.resolve(workspaceRoot, trimmed);
+    return assertPathInsideRoot(workspaceRoot, joined);
+}
+function assertSafePathSegment(segment, label) {
+    if (!segment || segment.trim() !== segment) {
+        throw new Error(`${label} must be a non-empty string without leading or trailing whitespace`);
+    }
+    if (segment.includes("\0")) {
+        throw new Error(`${label} contains invalid characters`);
+    }
+    if (path_1.default.isAbsolute(segment)) {
+        throw new Error(`${label} must be a relative name, not an absolute path`);
+    }
+    const normalized = path_1.default.normalize(segment);
+    if (normalized.split(path_1.default.sep).some((p) => p === "..")) {
+        throw new Error(`${label} must not contain '..'`);
+    }
+}

package/dist/spawn.d.ts

@@ -0,0 +1,20 @@
+import { SpawnSyncReturns } from "child_process";
+/**
+ * Validates a single argv string for use with {@link spawnSyncSafe} (no shell).
+ */
+export declare function assertSafeSpawnArg(arg: string): void;
+export declare function assertSafeSpawnArgs(args: readonly string[]): string[];
+export declare function assertSafeExecutableRef(file: string): void;
+export declare function assertSpawnOk(result: SpawnSyncReturns<string | Buffer>, what: string): void;
+export interface SpawnSyncSafeOptions {
+    cwd?: string;
+    encoding?: BufferEncoding;
+    stdio?: "inherit" | "pipe" | "ignore";
+    maxBuffer?: number;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Runs a binary with argv (no shell). Use instead of execSync(string).
+ */
+export declare function spawnSyncSafe(file: string, args: readonly string[], options?: SpawnSyncSafeOptions): SpawnSyncReturns<string | Buffer>;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../src/spawn.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAO5D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAUpD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOrE;AAeD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqB1D;AAED,wBAAgB,aAAa,CACzB,MAAM,EAAE,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,EACzC,IAAI,EAAE,MAAM,GACb,IAAI,CAON;AAED,MAAM,WAAW,oBAAoB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,oBAAyB,GACnC,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,CAmBnC"}

package/dist/spawn.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeSpawnArg = assertSafeSpawnArg;
+exports.assertSafeSpawnArgs = assertSafeSpawnArgs;
+exports.assertSafeExecutableRef = assertSafeExecutableRef;
+exports.assertSpawnOk = assertSpawnOk;
+exports.spawnSyncSafe = spawnSyncSafe;
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * Validates the executable passed to spawn (no shell): basename-only CLIs or paths without ".." segments.
+ */
+const MAX_SPAWN_ARG_LENGTH = 1024 * 1024;
+/**
+ * Validates a single argv string for use with {@link spawnSyncSafe} (no shell).
+ */
+function assertSafeSpawnArg(arg) {
+    if (typeof arg !== "string") {
+        throw new Error("Spawn argument must be a string");
+    }
+    if (arg.includes("\0")) {
+        throw new Error("Spawn argument contains null byte");
+    }
+    if (arg.length > MAX_SPAWN_ARG_LENGTH) {
+        throw new Error("Spawn argument is too long");
+    }
+}
+function assertSafeSpawnArgs(args) {
+    const out = [];
+    for (const arg of args) {
+        assertSafeSpawnArg(arg);
+        out.push(arg);
+    }
+    return out;
+}
+function assertSafeCwd(cwd) {
+    if (cwd === undefined) {
+        return undefined;
+    }
+    if (typeof cwd !== "string" || cwd.includes("\0")) {
+        throw new Error("Working directory must be a string without null bytes");
+    }
+    if (cwd.length > 8192) {
+        throw new Error("Working directory path is too long");
+    }
+    return path_1.default.resolve(cwd);
+}
+function assertSafeExecutableRef(file) {
+    if (typeof file !== "string" || file.length === 0) {
+        throw new Error("Executable must be a non-empty string");
+    }
+    if (file.length > 4096) {
+        throw new Error("Executable path is too long");
+    }
+    if (/[\0\n\r]/.test(file)) {
+        throw new Error("Executable path contains invalid characters");
+    }
+    const hasDirSep = file.includes("/") || file.includes("\\");
+    if (!hasDirSep) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(file)) {
+            throw new Error("Invalid executable name");
+        }
+        return;
+    }
+    const normalized = path_1.default.normalize(file);
+    if (normalized.split(path_1.default.sep).includes("..")) {
+        throw new Error("Invalid executable path");
+    }
+}
+function assertSpawnOk(result, what) {
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0 && result.status !== null) {
+        throw new Error(`${what} failed (exit ${result.status})`);
+    }
+}
+/**
+ * Runs a binary with argv (no shell). Use instead of execSync(string).
+ */
+function spawnSyncSafe(file, args, options = {}) {
+    assertSafeExecutableRef(file);
+    const validatedArgs = assertSafeSpawnArgs(args);
+    const stdio = options.stdio === "inherit"
+        ? "inherit"
+        : options.stdio === "ignore"
+            ? "ignore"
+            : "pipe";
+    const cwd = assertSafeCwd(options.cwd);
+    return (0, child_process_1.spawnSync)(file, validatedArgs, {
+        cwd,
+        encoding: options.encoding ?? "utf8",
+        stdio,
+        shell: false,
+        maxBuffer: options.maxBuffer,
+        env: options.env,
+    });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@quark-hq/quark-security",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Shared validation, path-safety, and spawn helpers for Quark CLI tooling",
+  "keywords": [
+    "quark",
+    "security",
+    "path-traversal",
+    "spawn",
+    "validation",
+    "typescript"
+  ],
+  "homepage": "https://github.com/ackotech/quark#readme",
+  "bugs": {
+    "url": "https://github.com/ackotech/quark/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ackotech/quark.git",
+    "directory": "cli/quark-security"
+  },
+  "license": "MIT",
+  "author": "Acko Technologies",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "25.0.9",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.8.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest --watch",
+    "coverage": "jest --coverage"
+  }
+}