approval-md 0.1.0 → 0.3.0

package/dist/src/core/shlex.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shell word splitting and joining, for the one place this runtime reads a
+ * command as a RENDERING of an argv rather than as bytes it was handed
+ * (APRV-362).
+ *
+ * ## Why this exists at all
+ *
+ * Every harness hook is handed a command as a string, and the classifier reads
+ * that string. Codex's app-server is the exception: what it will execute is an
+ * argv, and the item-based API delivers that argv already joined into one
+ * string by `shlex_join` (`docs/codex-app-server-bridge.md`, question 1). A
+ * bridge that classified the joined string without ever naming the argv would
+ * be approving its own re-parse, and the gap between the two is where an
+ * approval could authorize words nobody read.
+ *
+ * So the bridge names the argv, and these functions are how. They are pure,
+ * total and exhaustively tested, which is what SPEC.md §11's deterministic-core
+ * rule asks of anything a decision rests on.
+ *
+ * ## The grammar, and why it is narrower than a shell's
+ *
+ * This is `shlex`, not a shell. It knows three things: runs of whitespace
+ * separate words, a single-quoted run is literal, and a backslash outside
+ * quotes makes the next character literal. It does NOT know operators: `>`,
+ * `|`, `&&` and `;` are ordinary characters in ordinary words. That is correct
+ * here, because what is being un-joined is an argv and an argv has no
+ * operators. The shell metacharacters in a real Codex call live INSIDE one word
+ * (`/bin/zsh -lc 'printf x > f'`), and the hook's own classifier is what reads
+ * that word as a script.
+ *
+ * A DOUBLE QUOTE outside a single-quoted run is refused rather than
+ * interpreted. A join never emits one: a word needing protection comes back
+ * single-quoted and a word not needing it comes back bare. So a bare `"` says
+ * the string was not produced by joining an argv, and this runtime will not
+ * guess whose escaping rules apply inside it. Refusing is the fail-closed
+ * direction and it costs nothing a real server sends.
+ *
+ * ## The round trip, and the one thing it does not claim
+ *
+ * {@link shlexJoin} quotes a word when, and only when, {@link shlexSplit} would
+ * otherwise read it as something else: an empty word, or one carrying
+ * whitespace, a quote or a backslash. That makes
+ * `shlexSplit(shlexJoin(argv)).argv` equal to `argv` for every argv, which is
+ * the property {@link shlexRoundTrips} states and the bridge checks before it
+ * binds either value.
+ *
+ * The converse is NOT claimed: `shlexJoin(shlexSplit(text).argv)` is a normal
+ * form of `text`, not `text` itself. A counterpart is free to quote more
+ * conservatively than this does (a join written for shell safety quotes `>` and
+ * `:`, which this one leaves bare), and byte equality with the received string
+ * would therefore mean pinning that counterpart's quoting predicate. This
+ * repository has no record of it and cannot acquire one here, so demanding
+ * equality would refuse traffic on a guess. What is demanded instead is
+ * {@link ShlexSplit.joinShaped}: words separated by exactly one space, which
+ * every join produces and which is checkable without knowing which characters
+ * it chose to quote. The bridge records the received string and the argv side
+ * by side so any remaining difference is visible rather than asserted away.
+ */
+export type ShlexSplit = {
+    ok: true;
+    argv: string[];
+    /**
+     * Were the words separated by exactly one space each, with none before
+     * the first or after the last?
+     *
+     * True of every string a join produces. False says the string reached
+     * this runtime some other way, which is a fact about the counterpart
+     * rather than about the argv, and the caller decides what to do with it.
+     */
+    joinShaped: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Split a joined command string into the argv it renders.
+ *
+ * Refuses rather than guessing on the three shapes whose reading is not agreed:
+ * an unterminated single-quoted run, a trailing backslash with nothing to
+ * escape, and a double quote outside a quoted run (see the module header).
+ */
+export declare function shlexSplit(text: string): ShlexSplit;
+/**
+ * Render an argv as one command string that {@link shlexSplit} reads back as
+ * the same argv.
+ *
+ * Minimal quoting: a word is emitted bare unless it is empty or carries
+ * whitespace, a quote or a backslash, in which case it is single-quoted with
+ * the `'\''` idiom for an embedded quote. That idiom closes the run, escapes
+ * one quote and opens the next, which is three pieces of ONE word rather than
+ * three words, because nothing separates them.
+ */
+export declare function shlexJoin(argv: readonly string[]): string;
+/**
+ * Does `argv` survive a render-and-re-split cycle unchanged?
+ *
+ * True for every argv this module can render, and checked anyway at the one
+ * call site that binds an argv to an approval: a parser bug here would bind
+ * words nobody is going to run, and the cost of proving otherwise is one pass
+ * over a short string.
+ */
+export declare function shlexRoundTrips(argv: readonly string[]): boolean;

package/dist/src/core/shlex.js

@@ -0,0 +1,159 @@
+/**
+ * Shell word splitting and joining, for the one place this runtime reads a
+ * command as a RENDERING of an argv rather than as bytes it was handed
+ * (APRV-362).
+ *
+ * ## Why this exists at all
+ *
+ * Every harness hook is handed a command as a string, and the classifier reads
+ * that string. Codex's app-server is the exception: what it will execute is an
+ * argv, and the item-based API delivers that argv already joined into one
+ * string by `shlex_join` (`docs/codex-app-server-bridge.md`, question 1). A
+ * bridge that classified the joined string without ever naming the argv would
+ * be approving its own re-parse, and the gap between the two is where an
+ * approval could authorize words nobody read.
+ *
+ * So the bridge names the argv, and these functions are how. They are pure,
+ * total and exhaustively tested, which is what SPEC.md §11's deterministic-core
+ * rule asks of anything a decision rests on.
+ *
+ * ## The grammar, and why it is narrower than a shell's
+ *
+ * This is `shlex`, not a shell. It knows three things: runs of whitespace
+ * separate words, a single-quoted run is literal, and a backslash outside
+ * quotes makes the next character literal. It does NOT know operators: `>`,
+ * `|`, `&&` and `;` are ordinary characters in ordinary words. That is correct
+ * here, because what is being un-joined is an argv and an argv has no
+ * operators. The shell metacharacters in a real Codex call live INSIDE one word
+ * (`/bin/zsh -lc 'printf x > f'`), and the hook's own classifier is what reads
+ * that word as a script.
+ *
+ * A DOUBLE QUOTE outside a single-quoted run is refused rather than
+ * interpreted. A join never emits one: a word needing protection comes back
+ * single-quoted and a word not needing it comes back bare. So a bare `"` says
+ * the string was not produced by joining an argv, and this runtime will not
+ * guess whose escaping rules apply inside it. Refusing is the fail-closed
+ * direction and it costs nothing a real server sends.
+ *
+ * ## The round trip, and the one thing it does not claim
+ *
+ * {@link shlexJoin} quotes a word when, and only when, {@link shlexSplit} would
+ * otherwise read it as something else: an empty word, or one carrying
+ * whitespace, a quote or a backslash. That makes
+ * `shlexSplit(shlexJoin(argv)).argv` equal to `argv` for every argv, which is
+ * the property {@link shlexRoundTrips} states and the bridge checks before it
+ * binds either value.
+ *
+ * The converse is NOT claimed: `shlexJoin(shlexSplit(text).argv)` is a normal
+ * form of `text`, not `text` itself. A counterpart is free to quote more
+ * conservatively than this does (a join written for shell safety quotes `>` and
+ * `:`, which this one leaves bare), and byte equality with the received string
+ * would therefore mean pinning that counterpart's quoting predicate. This
+ * repository has no record of it and cannot acquire one here, so demanding
+ * equality would refuse traffic on a guess. What is demanded instead is
+ * {@link ShlexSplit.joinShaped}: words separated by exactly one space, which
+ * every join produces and which is checkable without knowing which characters
+ * it chose to quote. The bridge records the received string and the argv side
+ * by side so any remaining difference is visible rather than asserted away.
+ */
+/** Whitespace that separates words. Everything else is a word character. */
+const SEPARATORS = new Set([" ", "\t", "\n", "\r", "\f", "\v"]);
+/** A word must be quoted when a bare rendering would not read back as itself. */
+const NEEDS_QUOTING = /[\s'"\\]/u;
+/**
+ * Split a joined command string into the argv it renders.
+ *
+ * Refuses rather than guessing on the three shapes whose reading is not agreed:
+ * an unterminated single-quoted run, a trailing backslash with nothing to
+ * escape, and a double quote outside a quoted run (see the module header).
+ */
+export function shlexSplit(text) {
+    const argv = [];
+    let word = "";
+    /** Distinct from `word.length > 0`: `''` is an empty word, not no word. */
+    let started = false;
+    let joinShaped = true;
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (SEPARATORS.has(char)) {
+            // A separator before any word, one that is not a plain space, or a second
+            // one in a row: all three are shapes a join does not emit.
+            if (!started || char !== " " || SEPARATORS.has(text[index + 1] ?? ""))
+                joinShaped = false;
+            if (started) {
+                argv.push(word);
+                word = "";
+                started = false;
+            }
+            index += 1;
+            continue;
+        }
+        if (char === "'") {
+            const close = text.indexOf("'", index + 1);
+            if (close === -1) {
+                return {
+                    ok: false,
+                    reason: `a single-quoted run opened at offset ${String(index)} is never closed`,
+                };
+            }
+            word += text.slice(index + 1, close);
+            started = true;
+            index = close + 1;
+            continue;
+        }
+        if (char === '"') {
+            return {
+                ok: false,
+                reason: `a double quote at offset ${String(index)} is outside any quoted run, and a joined argv never carries one`,
+            };
+        }
+        if (char === "\\") {
+            if (index + 1 >= text.length) {
+                return { ok: false, reason: "the string ends in a backslash with nothing to escape" };
+            }
+            word += text[index + 1];
+            started = true;
+            index += 2;
+            continue;
+        }
+        word += char;
+        started = true;
+        index += 1;
+    }
+    if (started)
+        argv.push(word);
+    else if (text.length > 0)
+        joinShaped = false;
+    return { ok: true, argv, joinShaped };
+}
+/**
+ * Render an argv as one command string that {@link shlexSplit} reads back as
+ * the same argv.
+ *
+ * Minimal quoting: a word is emitted bare unless it is empty or carries
+ * whitespace, a quote or a backslash, in which case it is single-quoted with
+ * the `'\''` idiom for an embedded quote. That idiom closes the run, escapes
+ * one quote and opens the next, which is three pieces of ONE word rather than
+ * three words, because nothing separates them.
+ */
+export function shlexJoin(argv) {
+    return argv
+        .map((word) => word.length > 0 && !NEEDS_QUOTING.test(word) ? word : `'${word.split("'").join("'\\''")}'`)
+        .join(" ");
+}
+/**
+ * Does `argv` survive a render-and-re-split cycle unchanged?
+ *
+ * True for every argv this module can render, and checked anyway at the one
+ * call site that binds an argv to an approval: a parser bug here would bind
+ * words nobody is going to run, and the cost of proving otherwise is one pass
+ * over a short string.
+ */
+export function shlexRoundTrips(argv) {
+    const back = shlexSplit(shlexJoin(argv));
+    if (!back.ok || back.argv.length !== argv.length)
+        return false;
+    return back.argv.every((word, at) => word === argv[at]);
+}
+//# sourceMappingURL=shlex.js.map

package/dist/src/core/shlex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shlex.js","sourceRoot":"","sources":["../../../src/core/shlex.ts"],"names":[],"mappings":"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"}