@aragon-agent/cli 0.5.9 → 0.5.10

package/dist/update/npm-view.js

@@ -0,0 +1,133 @@
+/**
+ * The proxy-aware fallback probe (cli-auto-update-hardening H3 / section 5.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * NODE'S `fetch` (undici) IGNORES `HTTP_PROXY`. v1 recorded that as R-5 and
+ * accepted it: "the check fails, silently, forever". When the direct request
+ * returns `null`, the check now retries ONCE through the npm this machine
+ * already has, which honours `proxy`, `https-proxy`, `.npmrc` and any auth the
+ * user configured.
+ *
+ * WE DELEGATE RATHER THAN IMPLEMENT A PROXY (D-34). We do not read `.npmrc`, we
+ * do not parse `HTTP_PROXY`, and we attach credentials to nothing - D-13's "NO
+ * CREDENTIALS, EVER" is untouched because we never see them. We run the command
+ * the user could have typed and read one version string out of its JSON.
+ *
+ * `execFile` HERE, `spawn` IN `installer.ts`, AND THAT IS NOT AN INCONSISTENCY
+ * (D-36 / C-20). v1's IF-3 rejected `execFile` for the installer because it
+ * forwards neither `stdio` nor `detached`. This probe wants neither: it wants
+ * the buffered stdout `execFile` exists to provide, and it must NOT be detached.
+ * `timeout` is likewise safe here and forbidden there - a killed `npm view` has
+ * written nothing, a killed `npm install -g` has left a broken global install.
+ */
+import { execFile } from 'node:child_process';
+import process from 'node:process';
+import { cleanInstallEnv, resolveNpmCli } from './installer.js';
+import { UPDATE_LIMITS } from './limits.js';
+/**
+ * The argv this probe is allowed to build. Exported for AC-47's assertion, on
+ * the `buildInstallArgs` precedent.
+ *
+ * `--registry` IS NOT OPTIONAL, and leaving it out was a real divergence (P1-4 /
+ * D-41). The HTTP path resolves `update.registry` through `resolveRegistryUrl`;
+ * `npm view` without the flag obeys whatever `.npmrc` says. The two would then
+ * answer about DIFFERENT REGISTRIES - and the population where they differ is a
+ * mirror-configured corporate machine, which is the same population this
+ * fallback exists for. The `registry` passed in is the already-resolved string
+ * `runCheck` computed, so the two probes describe one registry by construction.
+ *
+ * Auth is unaffected: `--registry` selects a URL, and npm still applies whatever
+ * `.npmrc` credentials are scoped to it. We neither read nor forward any (D-13).
+ */
+export function buildNpmViewArgs(npmCliJs, packageName, distTag, registry) {
+    return [
+        npmCliJs,
+        'view',
+        `${packageName}@${distTag}`,
+        '--json',
+        '--loglevel=error',
+        `--registry=${registry}`,
+    ];
+}
+/**
+ * Normalise `npm view`'s object into the SAME shape `fetchLatestManifest`
+ * returns, so `decideUpdate` cannot tell the two sources apart.
+ *
+ * `npm view pkg@tag --json` on a dist-tag yields one object. An ARRAY comes back
+ * for a range, which we never send - but npm is not ours, so take the last
+ * element rather than failing the whole probe on a shape we did not ask for.
+ */
+function normalise(parsed) {
+    const one = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+    if (!one || typeof one !== 'object')
+        return null;
+    const doc = one;
+    if (typeof doc.name !== 'string' || typeof doc.version !== 'string')
+        return null;
+    return {
+        name: doc.name,
+        version: doc.version,
+        ...(doc.engines && typeof doc.engines === 'object'
+            ? { engines: { ...(typeof doc.engines.node === 'string' ? { node: doc.engines.node } : {}) } }
+            : {}),
+        // Present ONLY when the version is deprecated. npm writes a string, but
+        // `true` appears in the wild; both mean "do not auto-install this".
+        ...(doc.deprecated !== undefined ? { deprecated: String(doc.deprecated) } : {}),
+    };
+}
+/**
+ * Ask the machine's own npm what the dist-tag points at, or `null`.
+ *
+ * NEVER THROWS - the same contract as `fetchLatestManifest`, for the same
+ * reason: the only caller is a background timer whose entire contract is that
+ * the user does not find out. Any non-zero exit, any timeout, any unparseable
+ * stdout and a `resolveNpmCli()` of `null` all resolve to `null`.
+ *
+ * NO BARE-`npm`-ON-PATH FALLBACK, for the reason `installer.ts` already gives:
+ * on Windows that resolves to `npm.cmd`, which U-2 forbids.
+ */
+export function fetchLatestViaNpm(registry, packageName, distTag, deps = {}) {
+    return new Promise((settle) => {
+        const npmCliJs = deps.npmCliPath !== undefined ? deps.npmCliPath : resolveNpmCli();
+        if (!npmCliJs) {
+            settle(null);
+            return;
+        }
+        const run = deps.execFileImpl ?? execFile;
+        const options = {
+            // C-7, spelled out rather than inherited: this argv carries a package name
+            // read from a manifest on disk and a registry URL from config.
+            shell: false,
+            windowsHide: true,
+            timeout: deps.timeoutMs ?? UPDATE_LIMITS.npmViewTimeoutMs,
+            maxBuffer: UPDATE_LIMITS.manifestMaxBytes,
+            env: cleanInstallEnv(deps.env ?? process.env),
+        };
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            settle(value);
+        };
+        try {
+            run(process.execPath, buildNpmViewArgs(npmCliJs, packageName, distTag, registry), options, (error, stdout) => {
+                if (error) {
+                    finish(null);
+                    return;
+                }
+                try {
+                    finish(normalise(JSON.parse(String(stdout))));
+                }
+                catch {
+                    finish(null);
+                }
+            });
+        }
+        catch {
+            // `execFile` can throw synchronously on a bad argv or a missing binary.
+            finish(null);
+        }
+    });
+}

package/dist/update/registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The registry check (cli-auto-update section 3.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * One `GET`, one small JSON document, and NEVER A THROW. Transport rules follow
+ * C-8 verbatim - `AbortController` timeout, `redirect: 'manual'` with the
+ * allow-check repeated on every hop, a running byte ceiling, an injectable
+ * `fetchImpl` so every test is offline.
+ *
+ * NO CREDENTIALS, EVER (D-13). An updater that reads `_authToken` out of
+ * `.npmrc` and attaches it to a user-configurable URL is a credential
+ * exfiltration primitive the moment `update.registry` is mis-set. Private
+ * registry users point `update.registry` at a mirror they can read anonymously,
+ * or set `update.mode: off`.
+ */
+import type { LatestManifest } from './types.js';
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export interface RegistryDeps {
+    fetchImpl?: typeof fetch;
+    /** `aragon-agent-cli/<version>`; identifies us to the registry's logs. */
+    userAgent?: string;
+    timeoutMs?: number;
+}
+/**
+ * `config.update.registry` -> `ARAGON_UPDATE_REGISTRY` -> `npm_config_registry`
+ * -> the default.
+ *
+ * A value that does not parse as `http(s):` FALLS BACK rather than throwing:
+ * this runs on a background timer, and a typo in a config file must degrade to
+ * "checks the public registry" and not to "the CLI reports an error it cannot
+ * explain". `npm_config_registry` is read last and is what makes `aragon`
+ * inherit an enterprise mirror with no configuration at all.
+ */
+export declare function resolveRegistryUrl(configured: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * `<registry>/@scope%2Fname/<distTag>`.
+ *
+ * THE SCOPE SEPARATOR MUST BE PERCENT-ENCODED. `encodeURIComponent` does that
+ * and also makes the name safe to interpolate, which matters because the name
+ * comes from a manifest on disk rather than from a literal here (U-1).
+ */
+export declare function manifestUrl(registry: string, name: string, distTag: string): string;
+/**
+ * Fetch the dist-tag document, or `null`.
+ *
+ * NEVER THROWS. Any non-2xx, any parse failure, any timeout, any redirect loop
+ * and any oversize body all resolve to `null`, because every caller is a
+ * background timer whose entire contract is that the user does not find out. The
+ * caller counts a `null` as one consecutive failure and backs off.
+ */
+export declare function fetchLatestManifest(registry: string, name: string, distTag: string, deps?: RegistryDeps): Promise<LatestManifest | null>;

package/dist/update/registry.js

@@ -0,0 +1,161 @@
+/**
+ * The registry check (cli-auto-update section 3.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * One `GET`, one small JSON document, and NEVER A THROW. Transport rules follow
+ * C-8 verbatim - `AbortController` timeout, `redirect: 'manual'` with the
+ * allow-check repeated on every hop, a running byte ceiling, an injectable
+ * `fetchImpl` so every test is offline.
+ *
+ * NO CREDENTIALS, EVER (D-13). An updater that reads `_authToken` out of
+ * `.npmrc` and attaches it to a user-configurable URL is a credential
+ * exfiltration primitive the moment `update.registry` is mis-set. Private
+ * registry users point `update.registry` at a mirror they can read anonymously,
+ * or set `update.mode: off`.
+ */
+import process from 'node:process';
+import { UPDATE_LIMITS } from './limits.js';
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/**
+ * `config.update.registry` -> `ARAGON_UPDATE_REGISTRY` -> `npm_config_registry`
+ * -> the default.
+ *
+ * A value that does not parse as `http(s):` FALLS BACK rather than throwing:
+ * this runs on a background timer, and a typo in a config file must degrade to
+ * "checks the public registry" and not to "the CLI reports an error it cannot
+ * explain". `npm_config_registry` is read last and is what makes `aragon`
+ * inherit an enterprise mirror with no configuration at all.
+ */
+export function resolveRegistryUrl(configured, env = process.env) {
+    const candidates = [configured, env.ARAGON_UPDATE_REGISTRY, env.npm_config_registry];
+    for (const candidate of candidates) {
+        const text = candidate?.trim();
+        if (!text)
+            continue;
+        try {
+            const url = new URL(text);
+            // `http:` is accepted for a LAN mirror; nothing else is a registry.
+            if (url.protocol === 'https:' || url.protocol === 'http:') {
+                return text.replace(/\/+$/, '');
+            }
+        }
+        catch {
+            // Fall through to the next candidate.
+        }
+    }
+    return DEFAULT_REGISTRY;
+}
+/**
+ * `<registry>/@scope%2Fname/<distTag>`.
+ *
+ * THE SCOPE SEPARATOR MUST BE PERCENT-ENCODED. `encodeURIComponent` does that
+ * and also makes the name safe to interpolate, which matters because the name
+ * comes from a manifest on disk rather than from a literal here (U-1).
+ */
+export function manifestUrl(registry, name, distTag) {
+    return `${registry.replace(/\/+$/, '')}/${encodeURIComponent(name)}/${encodeURIComponent(distTag)}`;
+}
+function isRegistryUrl(raw) {
+    try {
+        const url = new URL(raw);
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/** Read a response body, aborting as soon as it passes `maxBytes` (C-8). */
+async function readCapped(response, maxBytes) {
+    const declared = Number(response.headers.get('content-length') ?? '0');
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw new Error(`registry response is ${declared} bytes (max ${maxBytes})`);
+    }
+    const body = response.body;
+    // No stream (a mocked `Response`, or a 204): fall back to `text()`, which the
+    // Content-Length gate above has already bounded when the header was honest.
+    if (!body) {
+        const text = await response.text();
+        if (text.length > maxBytes)
+            throw new Error(`registry response exceeded ${maxBytes} bytes`);
+        return text;
+    }
+    const chunks = [];
+    let total = 0;
+    // Content-Length is advisory; the running total is the real gate.
+    for await (const chunk of body) {
+        total += chunk.byteLength;
+        if (total > maxBytes)
+            throw new Error(`registry response exceeded ${maxBytes} bytes`);
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf-8');
+}
+/**
+ * Fetch the dist-tag document, or `null`.
+ *
+ * NEVER THROWS. Any non-2xx, any parse failure, any timeout, any redirect loop
+ * and any oversize body all resolve to `null`, because every caller is a
+ * background timer whose entire contract is that the user does not find out. The
+ * caller counts a `null` as one consecutive failure and backs off.
+ */
+export async function fetchLatestManifest(registry, name, distTag, deps = {}) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const timeoutMs = deps.timeoutMs ?? UPDATE_LIMITS.checkTimeoutMs;
+    let current = manifestUrl(registry, name, distTag);
+    try {
+        for (let hop = 0; hop <= UPDATE_LIMITS.maxRedirects; hop += 1) {
+            // Re-checked on EVERY hop: a registry that 302s to `file:` or to an
+            // internal address would otherwise be a free SSRF (C-8).
+            if (!isRegistryUrl(current))
+                return null;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let response;
+            try {
+                response = await doFetch(current, {
+                    redirect: 'manual',
+                    signal: controller.signal,
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': deps.userAgent ?? 'aragon-agent-cli',
+                    },
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (response.status >= 300 && response.status < 400) {
+                const location = response.headers.get('location');
+                if (!location)
+                    return null;
+                current = new URL(location, current).toString();
+                continue;
+            }
+            if (!response.ok)
+                return null;
+            const text = await readCapped(response, UPDATE_LIMITS.manifestMaxBytes);
+            const parsed = JSON.parse(text);
+            if (typeof parsed?.name !== 'string' || typeof parsed?.version !== 'string')
+                return null;
+            return {
+                name: parsed.name,
+                version: parsed.version,
+                ...(parsed.engines && typeof parsed.engines === 'object'
+                    ? { engines: { ...(typeof parsed.engines.node === 'string'
+                                ? { node: parsed.engines.node }
+                                : {}) } }
+                    : {}),
+                // Present ONLY when the version is deprecated. npm writes a string, but
+                // `true` appears in the wild; both mean "do not auto-install this".
+                ...(parsed.deprecated !== undefined
+                    ? { deprecated: String(parsed.deprecated) }
+                    : {}),
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/update/semver.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Semver comparison and the update decision (cli-auto-update section 3.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * HAND-WRITTEN AND NOT `semver`. The package has no such dependency
+ * (`package.json`), and this feature needs three questions answered - "is B
+ * newer than A", "is B a prerelease", "does this Node satisfy that range" - on a
+ * document the registry writes and npm itself only warns about. Adding a
+ * transitive dependency to an auto-updater, of all things, is the one place the
+ * supply-chain argument in R-1 cuts hardest.
+ *
+ * PURE: no I/O, no clock, no process. Every function here is total and none of
+ * them throws.
+ */
+import type { LatestManifest } from './types.js';
+/**
+ * The form a version must have before it is interpolated into `npm install`'s
+ * argv (section 3.5 / AC-24).
+ *
+ * ANCHORED AND WITHOUT `v`: a registry that answered `"1.0.0; rm -rf /"` must
+ * never reach `execFile`. With `shell: false` this is not an injection surface
+ * to begin with, but the rejection is what makes that claim checkable rather
+ * than reasoned, and it also satisfies `fetch-source.ts` rule 3 (no leading `-`)
+ * by construction.
+ */
+export declare const STRICT_VERSION_RE: RegExp;
+export interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Dot-separated prerelease identifiers, or `[]` for a release. */
+    prerelease: string[];
+}
+/** Parse a semver string, or `null` when it is not one. Never throws. */
+export declare function parseSemver(raw: unknown): Semver | null;
+export declare function isPrerelease(raw: string): boolean;
+/**
+ * `-1 | 0 | 1`. An UNPARSEABLE version sorts BELOW a parseable one and equal to
+ * another unparseable one, so a garbage registry answer can never read as newer
+ * than what is installed.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Does `nodeVersion` satisfy `engines.node`?
+ *
+ * FAILS OPEN, and that is a decision rather than an oversight (D-15). Handled
+ * forms are `>=X`, `>=X.Y.Z`, `>X`, `<X`, `<=X`, `=X`, `^X`, `~X`, `X.x`, and
+ * `||`-joined unions of those, with space-separated clauses inside a union
+ * ANDed together. Anything this cannot parse returns `true`, matching npm's own
+ * default of warning rather than refusing.
+ *
+ * Failing CLOSED here would mean a syntax we did not anticipate silently freezes
+ * every user's updates forever, with no message and no way to find out - the
+ * worse of the two errors by a wide margin. A range we DID understand and that
+ * genuinely excludes this Node yields `false`, and the caller turns that into a
+ * `node-too-old` notice so the user is told to upgrade Node rather than left
+ * wondering.
+ */
+export declare function satisfiesNodeRange(range: string | undefined, nodeVersion: string): boolean;
+export type UpdateAction = 'install' | 'notify' | 'none';
+export interface UpdateDecision {
+    action: UpdateAction;
+    reason: 'up-to-date' | 'prerelease' | 'deprecated' | 'node-too-old' | 'skipped' | 'newer-available';
+}
+export interface DecideUpdateInput {
+    /** The version this process is running. */
+    local: string;
+    manifest: Pick<LatestManifest, 'version' | 'engines' | 'deprecated'>;
+    /** `process.versions.node`, injected so the decision is testable offline. */
+    nodeVersion: string;
+    /** `state.skippedVersion`; `''` when the user has skipped nothing. */
+    skippedVersion: string;
+}
+/**
+ * Should we install, merely report, or say nothing? (section 3.4)
+ *
+ * ORDER IS SEMANTIC. `up-to-date` is answered first because it is the
+ * overwhelmingly common case and the cheapest; `skipped` comes before the
+ * quality gates so a user who typed `/update skip` is not told about a
+ * prerelease they already declined. Only a range we UNDERSTOOD and that excludes
+ * this Node produces `notify`; every other rejection is silent (`none`).
+ *
+ * The SOURCE and the MODE are deliberately NOT inputs here. This function
+ * answers "is that version worth having"; whether this machine may install it is
+ * the service's question, and folding the two would make a pure decision depend
+ * on the filesystem.
+ */
+export declare function decideUpdate(input: DecideUpdateInput): UpdateDecision;