peaks-loop 4.1.2 → 4.1.3

package/dist/services/readonly-surface/argv-guard.js

@@ -0,0 +1,164 @@
+/**
+ * Parameter-injection guard for the read-only surface.
+ *
+ * THE ATTACK. An argv template has placeholder slots (`request show <rid>`). If a
+ * placeholder value is pasted into a command LINE, the value `--apply` stops being
+ * a request id and becomes a flag - the semantics of the call are inverted by its
+ * own data. Two independent defences, both required (spec §8.1):
+ *
+ *   1. TYPE WHITELIST - every placeholder declares a type, and the value must
+ *      satisfy it. No type admits a leading `-`, so a flag-shaped value is never a
+ *      legal value of any placeholder.
+ *   2. ARRAY PASSING - `buildArgv` returns `string[]`. The caller passes the array
+ *      to the process API with shell parsing disabled (`readonlySpawnOptions`), so
+ *      no value is ever re-tokenized by a shell.
+ *
+ * Defence 2 alone is not enough: `spawn(..., {shell:false})` still hands `--apply`
+ * to the CLI as a real flag. Defence 1 alone is not enough: a caller that joins
+ * the array into a string reintroduces the shell. Hence both.
+ */
+import { isAbsolute } from 'node:path';
+/** Fallback pattern for a `slug` placeholder that declares none. */
+const DEFAULT_SLUG_PATTERN = '^[a-z0-9][a-z0-9-]*$';
+/** Upper bound on any single placeholder value, whatever its type. */
+export const READONLY_VALUE_MAX_LENGTH = 200;
+/** The process options that keep the array from being re-parsed by a shell. */
+export function readonlySpawnOptions() {
+    return { shell: false };
+}
+function reject(param, code, message) {
+    return { ok: false, param, code, message };
+}
+/**
+ * Control characters, matched by Unicode category rather than by a literal range:
+ * a hand-written `\x00-\x1f` class is a lint error (`no-control-regex`) precisely
+ * because such a range in a pattern is usually a bug, and `\p{Cc}` says what is
+ * meant without spelling out code points.
+ */
+function hasControlCharacter(value) {
+    return /\p{Cc}/u.test(value);
+}
+/**
+ * The rules that hold for EVERY type, before any type-specific rule runs. A
+ * leading `-` is refused here, so no type can carry a flag into the argv.
+ */
+function precheckCommon(param, raw) {
+    if (typeof raw !== 'string') {
+        return reject(param, 'NOT_A_STRING', `Parameter ${param} must be a string.`);
+    }
+    if (raw.length === 0)
+        return reject(param, 'EMPTY', `Parameter ${param} must not be empty.`);
+    if (raw.length > READONLY_VALUE_MAX_LENGTH) {
+        return reject(param, 'TOO_LONG', `Parameter ${param} exceeds ${READONLY_VALUE_MAX_LENGTH} characters.`);
+    }
+    if (raw.startsWith('-')) {
+        return reject(param, 'FLAG_SHAPED', `Parameter ${param} must not look like a flag: ${raw}`);
+    }
+    if (hasControlCharacter(raw)) {
+        return reject(param, 'CONTROL_CHARACTER', `Parameter ${param} must not contain control characters.`);
+    }
+    return { ok: true, value: raw };
+}
+function checkToken(param, value) {
+    if (/\s/.test(value)) {
+        return reject(param, 'WHITESPACE', `Parameter ${param} must be a single token.`);
+    }
+    return { ok: true, value };
+}
+function checkSlug(param, value, spec) {
+    const asToken = checkToken(param, value);
+    if (!asToken.ok)
+        return asToken;
+    const pattern = new RegExp(spec.pattern ?? DEFAULT_SLUG_PATTERN);
+    if (!pattern.test(value)) {
+        return reject(param, 'PATTERN_MISMATCH', `Parameter ${param} must match ${pattern.source}: ${value}`);
+    }
+    return { ok: true, value };
+}
+function checkEnum(param, value, spec) {
+    if (spec.values === undefined || !spec.values.includes(value)) {
+        return reject(param, 'NOT_IN_ENUM', `Parameter ${param} must be one of: ${(spec.values ?? []).join(', ')}`);
+    }
+    return { ok: true, value };
+}
+function checkInteger(param, value, spec) {
+    if (!/^[0-9]+$/.test(value)) {
+        return reject(param, 'NOT_AN_INTEGER', `Parameter ${param} must be an integer: ${value}`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    const min = spec.min ?? 0;
+    const max = spec.max ?? Number.MAX_SAFE_INTEGER;
+    if (parsed < min || parsed > max) {
+        return reject(param, 'OUT_OF_RANGE', `Parameter ${param} must be between ${min} and ${max}.`);
+    }
+    return { ok: true, value };
+}
+function checkPath(param, value) {
+    // Spaces are legal in a path and irrelevant under array passing; the absolute
+    // check is what keeps `--apply` and a bare word out.
+    if (!isAbsolute(value)) {
+        return reject(param, 'NOT_ABSOLUTE', `Parameter ${param} must be an absolute path.`);
+    }
+    return { ok: true, value };
+}
+const TYPE_CHECKS = {
+    token: (param, value) => checkToken(param, value),
+    slug: (param, value, spec) => checkSlug(param, value, spec),
+    enum: (param, value, spec) => checkEnum(param, value, spec),
+    integer: (param, value, spec) => checkInteger(param, value, spec),
+    path: (param, value) => checkPath(param, value)
+};
+/** Validate one placeholder value against its spec. */
+export function validatePlaceholderValue(param, spec, raw) {
+    const prechecked = precheckCommon(param, raw);
+    if (!prechecked.ok)
+        return prechecked;
+    return TYPE_CHECKS[spec.type](param, prechecked.value, spec);
+}
+function missingParam(param) {
+    return reject(param, 'EMPTY', `Parameter ${param} was not supplied.`);
+}
+/** A value is required for every placeholder present in the template. */
+function resolveParamValue(param, declared, values) {
+    if (declared === undefined)
+        return missingParam(param);
+    const supplied = values[param];
+    // Every placeholder in this surface is required (introspected), and a missing
+    // OPTIONAL value could only be honoured by also dropping the flag literal the
+    // loop has already pushed. Refusing is the honest answer.
+    if (supplied === undefined)
+        return missingParam(param);
+    return validatePlaceholderValue(param, declared, supplied);
+}
+function unknownParams(entry, values) {
+    for (const name of Object.keys(values)) {
+        if (!(name in entry.params)) {
+            return reject(name, 'NOT_A_STRING', `Entry ${entry.id} declares no parameter ${name}.`);
+        }
+    }
+    return undefined;
+}
+/**
+ * Render a whitelist entry into a concrete argv ARRAY.
+ *
+ * The output is never a string: literals and validated values are pushed as
+ * separate elements, so no value can contribute token boundaries. A parameter the
+ * entry does not declare is refused rather than appended.
+ */
+export function buildArgv(entry, values) {
+    const unexpected = unknownParams(entry, values);
+    if (unexpected !== undefined)
+        return unexpected;
+    const argv = [];
+    for (const segment of entry.argv) {
+        if (segment.kind === 'literal') {
+            argv.push(segment.value);
+            continue;
+        }
+        const resolved = resolveParamValue(segment.name, entry.params[segment.name], values);
+        if (!resolved.ok)
+            return resolved;
+        argv.push(resolved.value);
+    }
+    return { ok: true, argv };
+}

package/dist/services/readonly-surface/readonly-whitelist.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+/** Where the generator writes the artifact, relative to the package root. */
+export declare const READONLY_WHITELIST_RELATIVE_PATH = "contracts/readonly-argv-whitelist.json";
+declare const PlaceholderSpecSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        enum: "enum";
+        path: "path";
+        token: "token";
+        slug: "slug";
+        integer: "integer";
+    }>;
+    pattern: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodNumber>;
+    binding: z.ZodObject<{
+        kind: z.ZodEnum<{
+            option: "option";
+            positional: "positional";
+        }>;
+        token: z.ZodString;
+        required: z.ZodBoolean;
+    }, z.core.$strip>;
+    constraintSource: z.ZodEnum<{
+        introspected: "introspected";
+        handwritten: "handwritten";
+    }>;
+}, z.core.$strip>;
+declare const EntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    tool: z.ZodString;
+    commandPath: z.ZodArray<z.ZodString>;
+    argv: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"literal">;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"param">;
+        name: z.ZodString;
+    }, z.core.$strip>]>>;
+    params: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            enum: "enum";
+            path: "path";
+            token: "token";
+            slug: "slug";
+            integer: "integer";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+        binding: z.ZodObject<{
+            kind: z.ZodEnum<{
+                option: "option";
+                positional: "positional";
+            }>;
+            token: z.ZodString;
+            required: z.ZodBoolean;
+        }, z.core.$strip>;
+        constraintSource: z.ZodEnum<{
+            introspected: "introspected";
+            handwritten: "handwritten";
+        }>;
+    }, z.core.$strip>>;
+    introspection: z.ZodObject<{
+        optionTokens: z.ZodArray<z.ZodString>;
+        positionalCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const WhitelistSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    source: z.ZodString;
+    readOnlyDefinition: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodString;
+        commandPath: z.ZodArray<z.ZodString>;
+        argv: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"literal">;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"param">;
+            name: z.ZodString;
+        }, z.core.$strip>]>>;
+        params: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                enum: "enum";
+                path: "path";
+                token: "token";
+                slug: "slug";
+                integer: "integer";
+            }>;
+            pattern: z.ZodOptional<z.ZodString>;
+            values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodNumber>;
+            binding: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    option: "option";
+                    positional: "positional";
+                }>;
+                token: z.ZodString;
+                required: z.ZodBoolean;
+            }, z.core.$strip>;
+            constraintSource: z.ZodEnum<{
+                introspected: "introspected";
+                handwritten: "handwritten";
+            }>;
+        }, z.core.$strip>>;
+        introspection: z.ZodObject<{
+            optionTokens: z.ZodArray<z.ZodString>;
+            positionalCount: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlaceholderSpec = z.infer<typeof PlaceholderSpecSchema>;
+export type ReadOnlyWhitelistEntry = z.infer<typeof EntrySchema>;
+export type ReadOnlyWhitelist = z.infer<typeof WhitelistSchema>;
+/** Absolute path of the generated artifact for a package root. */
+export declare function resolveReadOnlyWhitelistPath(root?: string): string;
+/** Parse + validate the artifact text. Throws a zod error when the shape drifts. */
+export declare function parseReadOnlyWhitelist(text: string): ReadOnlyWhitelist;
+/** Read + validate the artifact. The only supported way to obtain it. */
+export declare function loadReadOnlyWhitelist(root?: string): ReadOnlyWhitelist;
+/** The param names an entry expects, in argv order. */
+export declare function paramNamesOf(entry: ReadOnlyWhitelistEntry): string[];
+/**
+ * The tool names the surface declares, in first-appearance order.
+ *
+ * This is the pre-tool interceptor's view of "what may be called", and it is
+ * computed HERE rather than in the MCP module on purpose: the interceptor must
+ * keep working when `src/services/mcp/` is deleted (spec §1), so it cannot reach
+ * into it for the answer. Grouping the entries by their `tool` field is the whole
+ * computation, and both readers do it from the same DATA.
+ */
+export declare function toolIdsOf(whitelist: ReadOnlyWhitelist): string[];
+/**
+ * Match a CONCRETE argv against the entries. A param slot consumes exactly one
+ * token, so `--apply` in a param slot still MATCHES here - refusing it is the
+ * validator's job (`argv-guard.ts`), not the matcher's. Keeping the two separate
+ * is what stops a rejected value from silently re-routing to another entry.
+ */
+export declare function matchReadOnlyEntry(whitelist: ReadOnlyWhitelist, argv: readonly string[]): ReadOnlyWhitelistEntry | undefined;
+export {};

package/dist/services/readonly-surface/readonly-whitelist.js

@@ -0,0 +1,107 @@
+/**
+ * The read-only argv whitelist, as DATA.
+ *
+ * WHY THIS IS A LOADER AND NOT AN IMPORT. The generated whitelist is read by two
+ * consumers that must survive the removal of the MCP module (spec §1): the
+ * pre-tool interceptor and, later, the MCP server. If either `import`ed the
+ * generated artifact it would become a static edge between them, and deleting
+ * the MCP module would break the gate. So the artifact stays a `.json` file and
+ * every reader goes through the filesystem. `tests/unit/standards/no-mcp-source-import.test.ts`
+ * pins that no module may `import` it.
+ *
+ * The shape is `{ schemaVersion, source, readOnlyDefinition, entries[] }`. Each
+ * entry is a full argv template (flags included) plus typed placeholders - the
+ * key is the WHOLE argv, never the top-level verb, because each named command
+ * family mixes read and write subcommands.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { repoRoot } from 'peaks-loop-shared/paths';
+/** Where the generator writes the artifact, relative to the package root. */
+export const READONLY_WHITELIST_RELATIVE_PATH = 'contracts/readonly-argv-whitelist.json';
+const PlaceholderBindingSchema = z.object({
+    /** `option` when the value is the argument of a flag, `positional` otherwise. */
+    kind: z.enum(['option', 'positional']),
+    /** The flag token (`--role`) or the positional name (`request-id`). */
+    token: z.string().min(1),
+    required: z.boolean()
+});
+const PlaceholderSpecSchema = z.object({
+    type: z.enum(['slug', 'enum', 'token', 'integer', 'path']),
+    pattern: z.string().min(1).optional(),
+    values: z.array(z.string().min(1)).min(1).optional(),
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    default: z.number().int().optional(),
+    /**
+     * Where the placeholder lives and whether the REGISTRY makes it mandatory.
+     * A placeholder present in the template is always supplied a value; this
+     * field carries the introspected fact, not the template's demand.
+     */
+    binding: PlaceholderBindingSchema,
+    /** `introspected` when the registry supplied the constraint, else `handwritten`. */
+    constraintSource: z.enum(['introspected', 'handwritten'])
+});
+const ArgvSegmentSchema = z.union([
+    z.object({ kind: z.literal('literal'), value: z.string().min(1) }),
+    z.object({ kind: z.literal('param'), name: z.string().min(1) })
+]);
+const EntrySchema = z.object({
+    id: z.string().min(1),
+    tool: z.string().min(1),
+    commandPath: z.array(z.string().min(1)).min(1),
+    argv: z.array(ArgvSegmentSchema).min(1),
+    params: z.record(z.string(), PlaceholderSpecSchema),
+    introspection: z.object({
+        optionTokens: z.array(z.string().min(1)),
+        positionalCount: z.number().int().gte(0)
+    })
+});
+const WhitelistSchema = z.object({
+    schemaVersion: z.literal(1),
+    source: z.string().min(1),
+    readOnlyDefinition: z.string().min(1),
+    entries: z.array(EntrySchema).min(1)
+});
+/** Absolute path of the generated artifact for a package root. */
+export function resolveReadOnlyWhitelistPath(root = repoRoot) {
+    return join(root, READONLY_WHITELIST_RELATIVE_PATH);
+}
+/** Parse + validate the artifact text. Throws a zod error when the shape drifts. */
+export function parseReadOnlyWhitelist(text) {
+    return WhitelistSchema.parse(JSON.parse(text));
+}
+/** Read + validate the artifact. The only supported way to obtain it. */
+export function loadReadOnlyWhitelist(root = repoRoot) {
+    return parseReadOnlyWhitelist(readFileSync(resolveReadOnlyWhitelistPath(root), 'utf8'));
+}
+/** The param names an entry expects, in argv order. */
+export function paramNamesOf(entry) {
+    return entry.argv.flatMap((segment) => (segment.kind === 'param' ? [segment.name] : []));
+}
+/**
+ * The tool names the surface declares, in first-appearance order.
+ *
+ * This is the pre-tool interceptor's view of "what may be called", and it is
+ * computed HERE rather than in the MCP module on purpose: the interceptor must
+ * keep working when `src/services/mcp/` is deleted (spec §1), so it cannot reach
+ * into it for the answer. Grouping the entries by their `tool` field is the whole
+ * computation, and both readers do it from the same DATA.
+ */
+export function toolIdsOf(whitelist) {
+    return [...new Set(whitelist.entries.map((entry) => entry.tool))];
+}
+/**
+ * Match a CONCRETE argv against the entries. A param slot consumes exactly one
+ * token, so `--apply` in a param slot still MATCHES here - refusing it is the
+ * validator's job (`argv-guard.ts`), not the matcher's. Keeping the two separate
+ * is what stops a rejected value from silently re-routing to another entry.
+ */
+export function matchReadOnlyEntry(whitelist, argv) {
+    return whitelist.entries.find((entry) => {
+        if (entry.argv.length !== argv.length)
+            return false;
+        return entry.argv.every((segment, index) => segment.kind === 'literal' ? segment.value === argv[index] : true);
+    });
+}

package/dist/services/readonly-surface/whitelist-generator.d.ts

@@ -0,0 +1,64 @@
+import type { Command } from 'commander';
+import { z } from 'zod';
+import { type ReadOnlyWhitelist } from './readonly-whitelist.js';
+/** The hand-authored input, relative to the package root. */
+export declare const READONLY_SURFACE_RELATIVE_PATH = "contracts/readonly-surface.json";
+/** The schema version of the artifact this module emits. */
+export declare const READONLY_WHITELIST_SCHEMA_VERSION = 1;
+declare const SurfaceEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    commandPath: z.ZodArray<z.ZodString>;
+    argv: z.ZodArray<z.ZodString>;
+    params: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            enum: "enum";
+            path: "path";
+            token: "token";
+            slug: "slug";
+            integer: "integer";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ReadOnlySurfaceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    readOnlyDefinition: z.ZodString;
+    note: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tools: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            commandPath: z.ZodArray<z.ZodString>;
+            argv: z.ZodArray<z.ZodString>;
+            params: z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodEnum<{
+                    enum: "enum";
+                    path: "path";
+                    token: "token";
+                    slug: "slug";
+                    integer: "integer";
+                }>;
+                pattern: z.ZodOptional<z.ZodString>;
+                values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                default: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReadOnlySurface = z.infer<typeof ReadOnlySurfaceSchema>;
+export type ReadOnlySurfaceEntry = z.infer<typeof SurfaceEntrySchema>;
+/** Build the artifact object from a surface declaration and a live program. */
+export declare function generateReadOnlyWhitelist(surface: ReadOnlySurface, program: Command): ReadOnlyWhitelist;
+/** Byte-stable serialization: two runs over the same input MUST match. */
+export declare function serializeReadOnlyWhitelist(whitelist: ReadOnlyWhitelist): string;
+/** Read + validate the hand-authored surface declaration. */
+export declare function loadReadOnlySurface(root?: string): ReadOnlySurface;
+/** Absolute path of the generated artifact. */
+export declare function readonlyWhitelistPath(root?: string): string;
+export {};