@danypops/vehicle-core 0.18.2 → 0.18.3

package/dist/cli-safety/assert-no-leading-flag-char.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Guards against the argv-injection class behind a well-known family of CLI-wrapper CVEs
+ * (simple-git's own history includes several): a caller-influenced string that starts with `-`
+ * can be parsed by the target CLI as a *flag* (`--upload-pack`, `--exec`, `--template`, `-c`
+ * config override) instead of the literal ref/path/pattern value the caller intended. Any Vehicle
+ * operation that hands a caller-supplied string to a shelled-out CLI's argv should run it through
+ * this check first, at the exact position it reaches that argv.
+ *
+ * This is a hard rejection with no exceptions -- it has no opinion about *why* a value starting
+ * with `-` might be needed and does not attempt to allow-list specific flags. A caller whose CLI
+ * genuinely accepts caller-influenced flag-shaped arguments needs a purpose-built allow-list of
+ * its own; this primitive only ever covers the common case of a value that should always be a
+ * literal.
+ */
+export declare class UnsafeCliArgument extends Error {
+    readonly value: string;
+    readonly fieldName?: string | undefined;
+    constructor(value: string, fieldName?: string | undefined);
+}
+/** Throws UnsafeCliArgument if `value` starts with `-`. `fieldName`, when given, names the field in the thrown error's own message for a caller with several distinct argv positions to check. */
+export declare function assertNoLeadingFlagChar(value: string, fieldName?: string): void;

package/dist/cli-safety/assert-no-leading-flag-char.js

@@ -0,0 +1,31 @@
+/**
+ * Guards against the argv-injection class behind a well-known family of CLI-wrapper CVEs
+ * (simple-git's own history includes several): a caller-influenced string that starts with `-`
+ * can be parsed by the target CLI as a *flag* (`--upload-pack`, `--exec`, `--template`, `-c`
+ * config override) instead of the literal ref/path/pattern value the caller intended. Any Vehicle
+ * operation that hands a caller-supplied string to a shelled-out CLI's argv should run it through
+ * this check first, at the exact position it reaches that argv.
+ *
+ * This is a hard rejection with no exceptions -- it has no opinion about *why* a value starting
+ * with `-` might be needed and does not attempt to allow-list specific flags. A caller whose CLI
+ * genuinely accepts caller-influenced flag-shaped arguments needs a purpose-built allow-list of
+ * its own; this primitive only ever covers the common case of a value that should always be a
+ * literal.
+ */
+export class UnsafeCliArgument extends Error {
+    value;
+    fieldName;
+    constructor(value, fieldName) {
+        super(fieldName
+            ? `"${value}" cannot be used as ${fieldName} -- it would be interpreted as a CLI flag, not a literal value`
+            : `"${value}" cannot be used as a CLI argument -- it would be interpreted as a flag, not a literal value`);
+        this.value = value;
+        this.fieldName = fieldName;
+        this.name = "UnsafeCliArgument";
+    }
+}
+/** Throws UnsafeCliArgument if `value` starts with `-`. `fieldName`, when given, names the field in the thrown error's own message for a caller with several distinct argv positions to check. */
+export function assertNoLeadingFlagChar(value, fieldName) {
+    if (value.startsWith("-"))
+        throw new UnsafeCliArgument(value, fieldName);
+}

package/dist/cli-safety/index.d.ts

@@ -0,0 +1 @@
+export * from "./assert-no-leading-flag-char.js";

package/dist/cli-safety/index.js

@@ -0,0 +1 @@
+export * from "./assert-no-leading-flag-char.js";

package/dist/index.d.ts

@@ -6,13 +6,15 @@
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
  * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
- * JSON), and concurrency (timer-based scheduling primitives) -- the latter
- * two are technical utilities, not Vehicle protocol capabilities, kept
- * distinct for that reason. Every symbol below is re-exported unchanged
+ * JSON), concurrency (timer-based scheduling primitives), and cli-safety
+ * (argv-injection guards for any operation shelling out to a CLI) -- the
+ * latter three are technical utilities, not Vehicle protocol capabilities,
+ * kept distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
+export * from "./cli-safety/index.js";
 export * from "./client/index.js";
 export * from "./concurrency/index.js";
 export * from "./content/index.js";

package/dist/index.js

@@ -6,13 +6,15 @@
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
  * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
- * JSON), and concurrency (timer-based scheduling primitives) -- the latter
- * two are technical utilities, not Vehicle protocol capabilities, kept
- * distinct for that reason. Every symbol below is re-exported unchanged
+ * JSON), concurrency (timer-based scheduling primitives), and cli-safety
+ * (argv-injection guards for any operation shelling out to a CLI) -- the
+ * latter three are technical utilities, not Vehicle protocol capabilities,
+ * kept distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
+export * from "./cli-safety/index.js";
 export * from "./client/index.js";
 export * from "./concurrency/index.js";
 export * from "./content/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.18.2",
+	"version": "0.18.3",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/cli-safety/assert-no-leading-flag-char.ts

@@ -0,0 +1,32 @@
+/**
+ * Guards against the argv-injection class behind a well-known family of CLI-wrapper CVEs
+ * (simple-git's own history includes several): a caller-influenced string that starts with `-`
+ * can be parsed by the target CLI as a *flag* (`--upload-pack`, `--exec`, `--template`, `-c`
+ * config override) instead of the literal ref/path/pattern value the caller intended. Any Vehicle
+ * operation that hands a caller-supplied string to a shelled-out CLI's argv should run it through
+ * this check first, at the exact position it reaches that argv.
+ *
+ * This is a hard rejection with no exceptions -- it has no opinion about *why* a value starting
+ * with `-` might be needed and does not attempt to allow-list specific flags. A caller whose CLI
+ * genuinely accepts caller-influenced flag-shaped arguments needs a purpose-built allow-list of
+ * its own; this primitive only ever covers the common case of a value that should always be a
+ * literal.
+ */
+export class UnsafeCliArgument extends Error {
+	constructor(
+		readonly value: string,
+		readonly fieldName?: string,
+	) {
+		super(
+			fieldName
+				? `"${value}" cannot be used as ${fieldName} -- it would be interpreted as a CLI flag, not a literal value`
+				: `"${value}" cannot be used as a CLI argument -- it would be interpreted as a flag, not a literal value`,
+		);
+		this.name = "UnsafeCliArgument";
+	}
+}
+
+/** Throws UnsafeCliArgument if `value` starts with `-`. `fieldName`, when given, names the field in the thrown error's own message for a caller with several distinct argv positions to check. */
+export function assertNoLeadingFlagChar(value: string, fieldName?: string): void {
+	if (value.startsWith("-")) throw new UnsafeCliArgument(value, fieldName);
+}

package/src/cli-safety/index.ts

@@ -0,0 +1 @@
+export * from "./assert-no-leading-flag-char.js";

package/src/index.ts

@@ -6,13 +6,15 @@
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
  * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
- * JSON), and concurrency (timer-based scheduling primitives) -- the latter
- * two are technical utilities, not Vehicle protocol capabilities, kept
- * distinct for that reason. Every symbol below is re-exported unchanged
+ * JSON), concurrency (timer-based scheduling primitives), and cli-safety
+ * (argv-injection guards for any operation shelling out to a CLI) -- the
+ * latter three are technical utilities, not Vehicle protocol capabilities,
+ * kept distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
+export * from "./cli-safety/index.js";
 export * from "./client/index.js";
 export * from "./concurrency/index.js";
 export * from "./content/index.js";