pi-lens 4.3.0 → 4.4.0

package/dist/clients/config-core/normalize.js

@@ -1,340 +0,0 @@
-/**
- * The validate/normalize half of the config pipeline (#2425, scope item 1).
- *
- * `RawConfig` (whatever `JSON.parse` returned) -> `validate(schema)` ->
- * `NormalizedConfig` (only fields the schema claims, each of the declared
- * shape). `merge.ts` then combines normalized configs across tiers, so the
- * merger never has to ask whether a value is the type it looks like.
- *
- * Four rules, the first three from `docs/public-api-stability.md`:
- *
- * 1. NEVER THROW. A user's config file is untrusted input; a schema violation
- *    degrades that field to absent and records why. A throw here would take
- *    down a session over a typo.
- * 2. UNKNOWN FIELDS ARE DROPPED, NOT KEPT. pi-lens's default is closed, unlike
- *    JSON Schema's — a schema opts into openness with `additionalProperties`.
- *    Keeping unknown fields would make every typo a silently-ignored setting,
- *    which is the failure users actually report.
- * 3. EVERY DROP IS RECORDED, with a stable `PILENS_CFG_*` code and a reason
- *    built from structure alone. No value ever reaches a record.
- * 4. THE WALK NEVER STOPS EARLY, and a user subtree is never passed through.
- *    Every node the validator returns was BUILT here, key by key, out of values
- *    this module checked. There is no arm on which a caller's object becomes
- *    part of the result by assertion.
- *
- * Rule 4 is the #2440 review finding, and it is worth stating why the two
- * pass-through arms it replaces were wrong rather than merely untidy. A schema
- * node that declares no `type` used to hand its value straight to the domain
- * type with `as ConfigValue`. That single assertion cost three properties at
- * once: the subtree's keys never met the prototype-key policy, so a
- * `{"__proto__": {...}}` node reached `out[name] = …` in BOTH builders and
- * re-parented the accumulator (serializing as `{}` while answering the
- * attacker's value on every field read); the subtree's depth was never counted,
- * so `MAX_CONFIG_DEPTH` bounded only the paths the schema happened to describe
- * and a 4000-deep blob went to the merger intact and overflowed the stack there;
- * and no record was produced for anything inside it, so the drop the pipeline
- * promises to explain was invisible. An always-walking normalizer fixes all
- * three by construction, which is the reason it is one normalizer and not three
- * patches.
- *
- * An OPAQUE node is still walked OPEN, not closed: a schema that claims nothing
- * about a node keeps that node's children, exactly as the pass-through did. What
- * changes is that they are copied, depth-counted, key-checked, and recorded. A
- * node that DOES name properties keeps its own (closed-by-default) policy.
- *
- * The walk is bounded on both axes that can grow: depth (a hand-written config
- * can nest arbitrarily) and record count (`MigrationRecordCollector`). Objects
- * already visited on the current path are refused, so a caller that hands in a
- * cyclic value gets a record rather than a stack overflow.
- */
-import { additionalPropertyPolicy, isKnownSchemaType, isPlainObject, isSchemaNode, itemsSchema, propertySchema, schemaType, } from "./schema.js";
-import { isUnsafeConfigKey, MAX_CONFIG_DEPTH, safeAssign, UNSAFE_KEY_REASON, } from "./safe-object.js";
-import { boundedKeyLabel, jsonTypeName, MigrationRecordCollector, migrationSubject, } from "./records.js";
-import { errorClassName } from "../error-class.js";
-/**
- * Re-exported from `safe-object.ts`, which owns it because `merge.ts` enforces
- * the same bound over values `validate()` may never have seen. Importers keep
- * their existing specifier; there is still one constant.
- */
-export { MAX_CONFIG_DEPTH };
-/** Sentinel for "this node produced no value". `undefined` is a legal JSON absence. */
-const DROPPED = Symbol("dropped");
-/**
- * The schema an opaque node's children are walked with: it governs nothing and
- * keeps everything. Spelled as a real node rather than `undefined` so the
- * "open" decision is made once, at the one place that decides it, instead of
- * being re-derived from an absent argument at every accessor.
- */
-const OPEN_SCHEMA = { additionalProperties: true };
-export function validate(raw, schema, options = {}) {
-    const collector = options.collector ?? new MigrationRecordCollector();
-    const file = options.file ?? "";
-    const context = {
-        collector,
-        file,
-        tier: options.tier,
-        path: [],
-    };
-    let walked;
-    try {
-        walked = walk(raw, schema, context, 0, new Set());
-    }
-    catch (error) {
-        // A throw here is a bug in this module, not in the user's config, but the
-        // contract above still holds: a config load never fails a session. The
-        // record says the document was dropped and names the error CLASS only,
-        // never its message, which could quote the file. `errorClassName` is the
-        // ONE implementation of that (#2451) — not `config-warn.ts`'s own
-        // `normalizeParseErrorReason`, which this "pure" module must not import:
-        // that is a sink (-> the degradation ledger), and importing one back in is
-        // exactly the cycle #2426 removed from `config-core/`.
-        record(context, {
-            code: "PILENS_CFG_0005",
-            key: "",
-            reason: `config validation failed internally (${errorClassName(error)}); document ignored`,
-        });
-        walked = DROPPED;
-    }
-    return {
-        value: walked === DROPPED ? undefined : walked,
-        records: collector.records,
-        droppedRecordCount: collector.droppedCount,
-    };
-}
-function pointerOf(path) {
-    return path.length === 0 ? "" : `/${path.join("/")}`;
-}
-function record(context, entry) {
-    const key = boundedKeyLabel(entry.key);
-    context.collector.add({
-        code: entry.code,
-        file: context.file,
-        key,
-        subject: migrationSubject(context.file, key),
-        reason: entry.reason,
-        tier: context.tier,
-    });
-}
-function walk(value, schema, context, depth, onPath) {
-    const pointer = pointerOf(context.path);
-    if (depth > MAX_CONFIG_DEPTH) {
-        record(context, {
-            code: "PILENS_CFG_0005",
-            key: pointer,
-            reason: `config nesting exceeds ${MAX_CONFIG_DEPTH} levels; ignored`,
-        });
-        return DROPPED;
-    }
-    if (typeof value === "object" && value !== null) {
-        if (onPath.has(value)) {
-            record(context, {
-                code: "PILENS_CFG_0005",
-                key: pointer,
-                reason: "config value refers to itself; ignored",
-            });
-            return DROPPED;
-        }
-    }
-    const declared = schemaType(schema);
-    if (declared === "object")
-        return walkObject(value, schema, context, depth, onPath);
-    if (declared === "array")
-        return walkArray(value, schema, context, depth, onPath);
-    if (isKnownSchemaType(declared)) {
-        return walkScalar(value, schema, context, declared);
-    }
-    // No `type` keyword, or one the core does not recognize: the schema is
-    // opaque about this node. The walk does not stop — see rule 4 in the module
-    // docs — it dispatches on the VALUE's shape instead, so the node is still
-    // copied, bounded, key-checked, and recorded. An unrecognized keyword is the
-    // schema's problem, not the user's, and `merge.ts` reads it the same way.
-    return walkOpaque(value, schema, context, depth, onPath);
-}
-/**
- * Walk a node the schema says nothing (useful) about.
- *
- * The dispatch is on the value, because that is the only thing left to dispatch
- * on. An object whose schema names no properties is walked OPEN — keeping its
- * children is what the old pass-through did, and dropping them now would turn a
- * defect fix into a silent feature removal. An object whose schema DOES name
- * properties keeps its own policy, which is closed by default.
- */
-function walkOpaque(value, schema, context, depth, onPath) {
-    if (isPlainObject(value)) {
-        const effective = claimsChildren(schema) ? schema : OPEN_SCHEMA;
-        return walkObject(value, effective, context, depth, onPath);
-    }
-    if (Array.isArray(value)) {
-        return walkArray(value, schema, context, depth, onPath);
-    }
-    return walkLeaf(value, schema, context);
-}
-/** True when the node declares something that governs its own children. */
-function claimsChildren(schema) {
-    if (!schema)
-        return false;
-    return (isSchemaNode(schema.properties) ||
-        isSchemaNode(schema.patternProperties) ||
-        schema.additionalProperties !== undefined);
-}
-/**
- * The one place a scalar enters the domain type, and it does so by NARROWING.
- *
- * `isConfigScalar` is a real predicate over the value, so nothing here asserts.
- * A value the JSON domain has no room for — `undefined`, a function, a symbol, a
- * bigint, `NaN`, an infinity — is dropped with a record rather than carried. A
- * parser cannot produce one, but `validate`'s input is `unknown` and a caller
- * handing in a live JS object can; `JSON.stringify` would silently turn `NaN`
- * into `null` several layers downstream, which is exactly the kind of quiet
- * corruption a validator exists to stop.
- */
-function walkLeaf(value, schema, context) {
-    if (!isConfigScalar(value)) {
-        record(context, {
-            code: "PILENS_CFG_0005",
-            key: pointerOf(context.path),
-            reason: `config value is not valid JSON data (${jsonTypeName(value)}); ignored`,
-        });
-        return DROPPED;
-    }
-    return checkEnum(value, schema, context) ? value : DROPPED;
-}
-function isConfigScalar(value) {
-    if (value === null)
-        return true;
-    const type = typeof value;
-    if (type === "string" || type === "boolean")
-        return true;
-    return type === "number" && Number.isFinite(value);
-}
-function walkObject(value, schema, context, depth, onPath) {
-    if (!isPlainObject(value)) {
-        record(context, {
-            code: "PILENS_CFG_0005",
-            key: pointerOf(context.path),
-            reason: `expected an object, got ${jsonTypeName(value)}; ignored`,
-        });
-        return DROPPED;
-    }
-    const nextPath = onPath.add(value);
-    const policy = additionalPropertyPolicy(schema);
-    const out = {};
-    for (const [name, child] of Object.entries(value)) {
-        // The prototype-key check runs BEFORE the schema is consulted. A schema
-        // could name `__proto__` as a property, and an open node keeps every key
-        // it is given; neither may reach the accumulator.
-        if (rejectUnsafeKey(name, context))
-            continue;
-        const childSchema = propertySchema(schema, name);
-        let effective = childSchema;
-        if (!childSchema) {
-            if (policy.kind === "drop") {
-                context.path.push(name);
-                record(context, {
-                    code: "PILENS_CFG_0004",
-                    key: pointerOf(context.path),
-                    reason: "unknown config field; ignored",
-                });
-                context.path.pop();
-                continue;
-            }
-            // `keep` walks the child with no schema at all, which `walkOpaque`
-            // reads as fully open; `validate` walks it with the declared one.
-            effective = policy.kind === "validate" ? policy.schema : undefined;
-        }
-        context.path.push(name);
-        const walked = walk(child, effective, context, depth + 1, nextPath);
-        context.path.pop();
-        if (walked !== DROPPED)
-            safeAssign(out, name, walked);
-    }
-    nextPath.delete(value);
-    return out;
-}
-/** Record and refuse a prototype-modifying key. Returns true when refused. */
-function rejectUnsafeKey(name, context) {
-    if (!isUnsafeConfigKey(name))
-        return false;
-    context.path.push(name);
-    record(context, {
-        code: "PILENS_CFG_0006",
-        key: pointerOf(context.path),
-        reason: UNSAFE_KEY_REASON,
-    });
-    context.path.pop();
-    return true;
-}
-function walkArray(value, schema, context, depth, onPath) {
-    if (!Array.isArray(value)) {
-        record(context, {
-            code: "PILENS_CFG_0005",
-            key: pointerOf(context.path),
-            reason: `expected an array, got ${jsonTypeName(value)}; ignored`,
-        });
-        return DROPPED;
-    }
-    const nextPath = onPath.add(value);
-    const items = itemsSchema(schema);
-    const out = [];
-    for (const [index, entry] of value.entries()) {
-        context.path.push(String(index));
-        const walked = walk(entry, items, context, depth + 1, nextPath);
-        context.path.pop();
-        if (walked !== DROPPED)
-            out.push(walked);
-    }
-    nextPath.delete(value);
-    return out;
-}
-/**
- * Type PREDICATES, not plain booleans: a check that only returned `true` would
- * leave the caller re-asserting the very fact it had just proved.
- */
-const SCALAR_CHECKS = {
-    string: (value) => typeof value === "string",
-    number: (value) => typeof value === "number" && Number.isFinite(value),
-    integer: (value) => typeof value === "number" && Number.isInteger(value),
-    boolean: (value) => typeof value === "boolean",
-    null: (value) => value === null,
-};
-/**
- * Check a node whose declared type is one of the five JSON scalars.
- *
- * `walk` has already established that `declared` is a recognized type and is
- * neither `object` nor `array`, so the lookup always hits. That is why there is
- * no pass-through arm here any more: the `!check` branch that used to return
- * `value as ConfigValue` was the second of the two assertion sites F1 named,
- * and the unrecognized-keyword case it existed for is now routed to
- * `walkOpaque` by the caller.
- */
-function walkScalar(value, schema, context, declared) {
-    const check = SCALAR_CHECKS[declared];
-    if (!check(value)) {
-        record(context, {
-            code: "PILENS_CFG_0005",
-            key: pointerOf(context.path),
-            reason: `expected ${declared}, got ${jsonTypeName(value)}; ignored`,
-        });
-        return DROPPED;
-    }
-    return checkEnum(value, schema, context) ? value : DROPPED;
-}
-/**
- * Enforce a declared `enum`. The record names the ALLOWED members, which are
- * schema text, and never the rejected value, which is user text.
- */
-function checkEnum(value, schema, context) {
-    const allowed = schema?.enum;
-    if (!Array.isArray(allowed))
-        return true;
-    if (allowed.some((candidate) => Object.is(candidate, value)))
-        return true;
-    record(context, {
-        code: "PILENS_CFG_0005",
-        key: pointerOf(context.path),
-        reason: `value is not one of ${allowed
-            .map((candidate) => JSON.stringify(candidate))
-            .join(", ")}; ignored`,
-    });
-    return false;
-}

package/dist/clients/config-core/process-spec.js

@@ -1,248 +0,0 @@
-/**
- * The trust-gated `ProcessSpec` (#2425, scope item 5).
- *
- * Today `createCustomServer` (`clients/lsp/config.ts`) builds an argv and an
- * env straight out of project-local JSON, with no gate at that seam; the only
- * trust check is far downstream in `lsp/index.ts`. This module is the type that
- * makes the gate a property of the VALUE instead of a property of one call
- * site: a spec knows which tier described it and what the host said about that
- * tier's trust, and `toSpawnArgs` is the only way to get spawnable arguments
- * out of it.
- *
- * THIS PR SPAWNS NOTHING. `toSpawnArgs` returns arguments; #2372 slice 2 hands
- * them to `safeSpawnAsync` at `createCustomServer`. Keeping the decision pure
- * is what lets the trust matrix be tested exhaustively without a child process.
- *
- * The gate, stated as a rule: a spec whose provenance tier is `project` or
- * `nested-project` yields spawn arguments only when BOTH the spec's own trust
- * decision and the host's CURRENT decision are `"trusted"`. Two conditions
- * rather than one, because they fail differently:
- *
- * - the spec's `trust` is the decision that applied when the config was read;
- * - `getProjectTrustState()` is the decision that applies now, and a session
- *   can revoke trust between the two. A spec that carried `trusted` in its own
- *   fields would otherwise be a permanent capability token.
- *
- * `unknown` does not pass for repo tiers. Elsewhere in pi-lens `unknown` is
- * fail-open, because an older host that never had `isProjectTrusted` never had
- * a decision to honor. Here it is fail-closed, and the asymmetry is deliberate:
- * `isToolInstallAllowedByTrust` gates pi-lens's OWN managed tools, while this
- * gates a command string a repository wrote.
- */
-import { incrementDegradationCount } from "../degradation-ledger.js";
-import { homeRelativePath } from "../path-utils.js";
-import { getProjectTrustGeneration, getProjectTrustState, } from "../project-trust.js";
-import { compareKeys, isRepoTier, } from "./provenance.js";
-/** Longest argv a spec may carry. A command line, not a file list. */
-export const MAX_ARGV_ENTRIES = 128;
-/** Total argv bytes a spec may carry. */
-const MAX_ARGV_BYTES = 32 * 1024;
-/** Most env entries a spec may carry. */
-export const MAX_ENV_ENTRIES = 64;
-/** Total env bytes (names plus values) a spec may carry. */
-export const MAX_ENV_BYTES = 16 * 1024;
-/** Longest timeout a spec may declare, in milliseconds. */
-export const MAX_TIMEOUT_MS = 10 * 60 * 1000;
-const CWD_MODES = ["root", "file-dir"];
-const INPUT_MODES = ["none", "stdin", "file"];
-function byteLength(text) {
-    return Buffer.byteLength(text, "utf8");
-}
-/**
- * Validate an untrusted description into a `ProcessSpec`.
- *
- * Pure and side-effect-free: a rejection is returned, not logged. The caller
- * knows which config file it was reading and turns the rejection into a
- * `MigrationRecord`; this module does not guess at a subsystem.
- *
- * Over-cap env is REFUSED rather than truncated. Silently dropping half a
- * process's environment produces a server that starts and then misbehaves,
- * which is strictly worse to diagnose than one that does not start.
- */
-export function buildProcessSpec(input) {
-    const argv = input.argv;
-    if (argv.length === 0) {
-        return reject("empty-argv", "argv is empty; a spec needs a command");
-    }
-    if (argv.length > MAX_ARGV_ENTRIES) {
-        return reject("argv-too-many", `argv has ${argv.length} entries, limit ${MAX_ARGV_ENTRIES}`);
-    }
-    if (!argv.every((entry) => typeof entry === "string")) {
-        return reject("argv-not-strings", "argv entries must all be strings");
-    }
-    const argvStrings = argv;
-    const argvBytes = argvStrings.reduce((total, entry) => total + byteLength(entry), 0);
-    if (argvBytes > MAX_ARGV_BYTES) {
-        return reject("argv-too-large", `argv is ${argvBytes} bytes, limit ${MAX_ARGV_BYTES}`);
-    }
-    if (argvStrings[0].length === 0) {
-        return reject("empty-argv", "argv[0] is empty; a spec needs a command");
-    }
-    const rawEnv = input.env ?? {};
-    const envNames = Object.keys(rawEnv);
-    if (envNames.length > MAX_ENV_ENTRIES) {
-        return reject("env-too-many", `env has ${envNames.length} entries, limit ${MAX_ENV_ENTRIES}`);
-    }
-    const env = {};
-    let envBytes = 0;
-    for (const name of envNames) {
-        const value = rawEnv[name];
-        if (typeof value !== "string") {
-            return reject("env-not-strings", "env values must all be strings");
-        }
-        envBytes += byteLength(name) + byteLength(value);
-        env[name] = value;
-    }
-    if (envBytes > MAX_ENV_BYTES) {
-        return reject("env-too-large", `env is ${envBytes} bytes, limit ${MAX_ENV_BYTES}`);
-    }
-    const cwdMode = input.cwdMode ?? "root";
-    if (!CWD_MODES.includes(cwdMode)) {
-        return reject("invalid-cwd-mode", "cwdMode must be root or file-dir");
-    }
-    const inputMode = input.inputMode ?? "none";
-    if (!INPUT_MODES.includes(inputMode)) {
-        return reject("invalid-input-mode", "inputMode must be none, stdin or file");
-    }
-    const timeoutMs = input.timeoutMs;
-    if (!Number.isFinite(timeoutMs) ||
-        timeoutMs <= 0 ||
-        timeoutMs > MAX_TIMEOUT_MS) {
-        return reject("invalid-timeout", `timeoutMs must be a finite value in (0, ${MAX_TIMEOUT_MS}]`);
-    }
-    return {
-        ok: true,
-        spec: {
-            argv: argvStrings,
-            env,
-            cwdMode,
-            inputMode,
-            timeoutMs,
-            provenance: input.provenance,
-            trust: input.trust ?? getProjectTrustState(),
-        },
-    };
-}
-function reject(code, reason) {
-    return { ok: false, rejection: { code, reason } };
-}
-/**
- * The degradation kind a refusal records under, reusing `project-trust.ts`'s
- * existing member rather than adding a parallel one. Aggregation across
- * install refusals and spawn refusals is the same question.
- */
-const TRUST_REFUSAL_KIND = "trust-refusal";
-/**
- * Turn a spec into spawn arguments, or refuse.
- *
- * Repo-tier specs need `spec.trust === "trusted"` AND a live host decision of
- * `"trusted"`. Operator-tier specs (built-in, global, env, cli, host) pass:
- * their content did not arrive with the checkout, and pi-lens's separate
- * host-level spawn gate (`isLspSpawnAllowedByTrust`) still applies downstream.
- *
- * Refusals go through `incrementDegradationCount`, which is the repo's choke
- * point for a REPEATED degradation: it writes the durable row on the first
- * occurrence and at power-of-two milestones, keeps the exact count, is bounded
- * per kind, and resets at `session_start` with the rest of the ledger. That is
- * why there is no once-latch in this module to re-arm — a second latch mirroring
- * the ledger is the defect the ledger exists to prevent.
- */
-export function toSpawnArgs(spec) {
-    const tier = spec.provenance.tier;
-    if (!isRepoTier(tier)) {
-        return { ok: true, args: spawnArgsOf(spec) };
-    }
-    const hostTrust = getProjectTrustState();
-    if (spec.trust !== "trusted") {
-        return refuse(spec, "spec-trust", hostTrust);
-    }
-    if (hostTrust !== "trusted") {
-        return refuse(spec, "host-trust", hostTrust);
-    }
-    return { ok: true, args: spawnArgsOf(spec) };
-}
-function spawnArgsOf(spec) {
-    return {
-        argv: spec.argv,
-        env: spec.env,
-        cwdMode: spec.cwdMode,
-        inputMode: spec.inputMode,
-        timeoutMs: spec.timeoutMs,
-    };
-}
-function refuse(spec, cause, hostTrust) {
-    const tier = spec.provenance.tier;
-    const command = spec.argv[0];
-    const reason = cause === "spec-trust"
-        ? `${tier} config command refused: config trust is ${spec.trust}`
-        : `${tier} config command refused: host trust is now ${hostTrust}`;
-    const trustGeneration = getProjectTrustGeneration();
-    const refusal = {
-        kind: "trust-refusal",
-        cause,
-        reason,
-        tier,
-        command,
-        specTrust: spec.trust,
-        hostTrust,
-        trustGeneration,
-    };
-    // Subject carries the trust GENERATION, the tier, and argv[0] only: enough to
-    // say which command was refused and in which trust episode, never enough to
-    // leak an argument or an env value.
-    //
-    // The generation belongs in the SUBJECT, not only in the metadata (#2440
-    // review finding F6). `incrementDegradationCount` keys its tally on
-    // `kind\0subject` and writes a durable row on the first occurrence and at
-    // power-of-two milestones. A generation-free subject therefore made one
-    // unbroken count across every trust episode of a session: revoke, refuse
-    // three times, re-grant, revoke again, and the next refusal is count 4 — not
-    // a power of two, so the second episode produces NO durable row at all and
-    // the count a reader sees does not describe either episode. Re-arming the
-    // subject per generation makes each episode its own bounded, durably-recorded
-    // series, which is what a per-episode question needs.
-    incrementDegradationCount({
-        kind: TRUST_REFUSAL_KIND,
-        subject: `config-command:g${trustGeneration}:${tier}:${command}`,
-        reason,
-        metadata: {
-            cause,
-            specTrust: spec.trust,
-            hostTrust,
-            trustGeneration,
-            configKey: spec.provenance.key,
-        },
-    });
-    return { ok: false, refusal };
-}
-/**
- * The ONLY projection of a spec for diagnostics or telemetry.
- *
- * Strips env VALUES and every argv entry after `argv[0]` (#2415 AC 4). Both are
- * places a secret genuinely lives: a token in `--header`, a key in an env value.
- * Env NAMES survive because a name is a label, and "which variables did this
- * server get" is the question an operator actually asks.
- */
-export function redactProcessSpec(spec) {
-    return {
-        command: spec.argv[0],
-        argvCount: spec.argv.length,
-        // `compareKeys`, not a bare `.sort()` (Sonar S2871) and not
-        // `localeCompare`: this projection is compared across machines, so its
-        // ordering may not depend on the machine's locale.
-        envNames: Object.keys(spec.env).sort(compareKeys),
-        envCount: Object.keys(spec.env).length,
-        cwdMode: spec.cwdMode,
-        inputMode: spec.inputMode,
-        timeoutMs: spec.timeoutMs,
-        tier: spec.provenance.tier,
-        configKey: spec.provenance.key,
-        // Home-relative for the same reason `provenanceView` is: a spec read from
-        // the operator's global config would otherwise put their account name on
-        // every diagnostic that named the file.
-        ...(spec.provenance.file === undefined
-            ? {}
-            : { file: homeRelativePath(spec.provenance.file) }),
-        trust: spec.trust,
-    };
-}