@endo-ui/license 1.4.0 → 1.4.1

package/README.md

@@ -32,6 +32,42 @@ private `@endo-ui/core` package.
 Local activation fails before validation or project mutation when `@endo-ui/license` is not
 already installed in the project. CI uses the generated isolated exact-version bootstrap instead.
 
+### Enterprise HTTP/HTTPS proxies
+
+EndoUI supports approved forward HTTP/HTTPS egress proxies for npm access. npm package-access
+validation runs through the npm CLI in an isolated temporary project so npm can honor its normal
+proxy, certificate-authority, and environment configuration. The temporary configuration still
+pins the `@endo-ui` scope and `NPM_TOKEN` authentication to `https://registry.npmjs.org/`; the token
+is never written into that temporary file.
+
+Configure an approved proxy with normal npm settings, for example:
+
+```bash
+npm config set --location=user proxy http://proxy.example:8080
+npm config set --location=user https-proxy http://proxy.example:8080
+# If the approved proxy uses an enterprise CA:
+npm config set --location=user cafile /path/to/company-ca.pem
+```
+
+Or provide standard proxy environment variables. PowerShell example:
+
+```powershell
+$env:HTTP_PROXY = "http://proxy.example:8080"
+$env:HTTPS_PROXY = "http://proxy.example:8080"
+```
+
+A forward network proxy is different from an internal npm repository or package mirror such as
+Artifactory, Nexus, Azure Artifacts, or Verdaccio. EndoUI does not redirect `NPM_TOKEN` to an
+alternate registry and does not recommend storing the customer EndoUI npm credential in a
+third-party or contractor-controlled repository manager. If organizational policy blocks
+`registry.npmjs.org` entirely instead of allowing it through an approved egress proxy, contact
+EndoUI Support rather than copying the customer npm credential into that repository.
+
+If an approved proxy performs TLS interception, the organization operating that trusted proxy can
+observe HTTPS request contents, including registry authorization headers. Use only proxy
+infrastructure approved to handle the customer's EndoUI package credential. Configure the
+organization's trusted CA instead of disabling npm or Node.js TLS verification.
+
 ## Upgrade
 
 Once EndoUI is activated, use Angular's update workflow rather than uninstalling and reinstalling
@@ -71,7 +107,9 @@ script and are not automatically refreshed.
 Commit the generated `scripts/endoui-license-ci.sh` and `scripts/endoui-license-ci.ps1` files.
 Store `NPM_TOKEN` and `ENDOUI_LICENSE_ID` in the CI provider's protected secret storage, then run
 the platform-appropriate generated script immediately after checkout and before dependency
-installation.
+installation. When CI requires an HTTP/HTTPS egress proxy, provide the same approved npm proxy
+configuration or `HTTP_PROXY` / `HTTPS_PROXY` environment variables to both the EndoUI activation
+step and the dependency-install step.
 
 CI authorization does not consume a human Seat. The scripts bootstrap the exact license-tool
 version that generated them, validate npm and ECAP access, and cache a signed authorization for

package/bin/activation.js

@@ -1,7 +1,7 @@
 import { activateCi, activateDeveloper } from "./api.js";
 import { configureAngularWorkspace } from "./angular-config.js";
 import { generateCiScripts } from "./ci-scripts.js";
-import { installCore } from "./core-install.js";
+import { installCore, isCoreReady } from "./core-install.js";
 import { verifyLease } from "./lease.js";
 import { validateNpmAccess } from "./npm-access.js";
 import { ensureEndoUiNpmrc } from "./npmrc.js";
@@ -22,6 +22,7 @@ const defaults = {
     npmrc: ensureEndoUiNpmrc,
     angular: configureAngularWorkspace,
     scripts: generateCiScripts,
+    coreReady: isCoreReady,
     install: installCore
 };
 export function resolveCiInputs(environment) {
@@ -58,10 +59,12 @@ export async function activateLocal(input, overrides = {}) {
     if (lease.user !== input.developer) {
         throw new Error("The signed EndoUI authorization does not match the named developer.");
     }
+    const coreReady = await dependencies.coreReady(cwd, version);
     await dependencies.npmrc(cwd);
     await dependencies.angular(cwd);
     await dependencies.scripts({ packageVersion: version, customer: lease.customer, licenseId: input.licenseId }, cwd);
-    await dependencies.install(cwd, version, npmToken);
+    if (!coreReady)
+        await dependencies.install(cwd, version, npmToken);
     await dependencies.writeLease(major(version), signedLease);
     return { version, lease };
 }

package/bin/ci-scripts.js

@@ -1,4 +1,4 @@
-import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 export function maskLicenseId(_licenseId) {
     return "********";
@@ -68,12 +68,34 @@ try {
 }
 `;
 }
+function comparableScript(content) {
+    return content
+        .replace(/\r\n/g, "\n")
+        .replace(/^# Generated: .*$/m, "# Generated: <date>");
+}
+async function writeScriptIfChanged(file, content, mode) {
+    try {
+        const existing = await readFile(file, "utf8");
+        if (comparableScript(existing) === comparableScript(content))
+            return;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    if (mode === undefined) {
+        await writeFile(file, content, "utf8");
+    }
+    else {
+        await writeFile(file, content, { encoding: "utf8", mode });
+    }
+}
 export async function generateCiScripts(metadata, cwd = process.cwd()) {
     const directory = path.join(cwd, "scripts");
     await mkdir(directory, { recursive: true });
     const shellPath = path.join(directory, "endoui-license-ci.sh");
-    await writeFile(shellPath, createShellCiScript(metadata), { encoding: "utf8", mode: 0o755 });
-    await writeFile(path.join(directory, "endoui-license-ci.ps1"), createPowerShellCiScript(metadata), "utf8");
+    await writeScriptIfChanged(shellPath, createShellCiScript(metadata), 0o755);
+    await writeScriptIfChanged(path.join(directory, "endoui-license-ci.ps1"), createPowerShellCiScript(metadata));
     if (process.platform !== "win32")
         await chmod(shellPath, 0o755);
 }

package/bin/core-install.js

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 const MAX_STDERR_LENGTH = 65_536;
 function redact(value, npmToken) {
     return npmToken ? value.split(npmToken).join("[REDACTED]") : value;
@@ -10,6 +12,26 @@ export function npmInstallFailure(specification, exitCode, stderr, npmToken, sig
         `npm exit code: ${exitCode ?? "unknown"}\n` +
         `Reason:\n${reason}`);
 }
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function isCoreReady(cwd, version) {
+    const manifest = await readJson(path.join(cwd, "package.json"));
+    const declared = Boolean(manifest?.dependencies?.["@endo-ui/core"] ??
+        manifest?.devDependencies?.["@endo-ui/core"] ??
+        manifest?.optionalDependencies?.["@endo-ui/core"]);
+    if (!declared)
+        return false;
+    const installed = await readJson(path.join(cwd, "node_modules", "@endo-ui", "core", "package.json"));
+    return installed?.["name"] === "@endo-ui/core" && installed?.["version"] === version;
+}
 export async function installCore(cwd = process.cwd(), version, npmToken) {
     const isWindows = process.platform === "win32";
     const command = isWindows
@@ -25,6 +47,7 @@ export async function installCore(cwd = process.cwd(), version, npmToken) {
             cwd,
             env: {
                 ...process.env,
+                NPM_CONFIG_SAVE_EXACT: "true",
                 ...(npmToken ? { NPM_TOKEN: npmToken } : {})
             },
             stdio: ["inherit", "inherit", "pipe"],

package/bin/npm-access.js

@@ -1,34 +1,110 @@
-export async function validateNpmAccess(token, version, request = fetch) {
-    let response;
-    try {
-        response = await request("https://registry.npmjs.org/@endo-ui%2Fcore", {
-            headers: {
-                Accept: "application/vnd.npm.install-v1+json",
-                Authorization: `Bearer ${token}`
-            }
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { NPMRC_REGION } from "./npmrc.js";
+const MAX_OUTPUT_LENGTH = 65_536;
+const NETWORK_ERROR_PATTERN = /\b(?:EAI_AGAIN|ECONNABORTED|ECONNREFUSED|ECONNRESET|ENETUNREACH|ENOTFOUND|ETIMEDOUT|ERR_SOCKET_TIMEOUT)\b/i;
+const PROXY_AUTH_PATTERN = /\b407\b|proxy authentication required/i;
+const TLS_ERROR_PATTERN = /\b(?:CERT_HAS_EXPIRED|DEPTH_ZERO_SELF_SIGNED_CERT|ERR_TLS_CERT_ALTNAME_INVALID|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE)\b/i;
+function appendOutput(current, chunk) {
+    return `${current}${chunk}`.slice(-MAX_OUTPUT_LENGTH);
+}
+function redact(value, token) {
+    return value.split(token).join("[REDACTED]");
+}
+async function runNpm(args, options) {
+    const isWindows = process.platform === "win32";
+    const command = isWindows ? process.env["ComSpec"] ?? "cmd.exe" : "npm";
+    const commandArgs = isWindows
+        ? ["/d", "/s", "/c", "npm", ...args]
+        : [...args];
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, commandArgs, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: false
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout = appendOutput(stdout, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = appendOutput(stderr, chunk);
         });
+        child.once("error", reject);
+        child.once("exit", exitCode => resolve({ exitCode, stdout, stderr }));
+    });
+}
+function npmFailure(result, token) {
+    const output = redact(`${result.stdout}\n${result.stderr}`, token);
+    if (/\bE401\b|401\s+Unauthorized/i.test(output)) {
+        return new Error("The npm token is invalid, expired, or revoked.");
+    }
+    if (/\bE403\b|\bE404\b|403\s+Forbidden|404\s+Not Found/i.test(output)) {
+        return new Error("The npm token does not have read access to @endo-ui/core.");
+    }
+    if (PROXY_AUTH_PATTERN.test(output)) {
+        return new Error("The configured npm network proxy rejected authentication while EndoUI was validating " +
+            "access to @endo-ui/core. Verify the organization's approved npm proxy credentials.");
+    }
+    if (TLS_ERROR_PATTERN.test(output)) {
+        return new Error("npm TLS validation failed while EndoUI was checking @endo-ui/core. Configure the organization's " +
+            "approved certificate authority through npm's cafile setting or the approved Node.js trust " +
+            "configuration; do not disable TLS verification.");
     }
-    catch {
-        throw new Error("Unable to contact npm to validate access to @endo-ui/core.");
+    if (NETWORK_ERROR_PATTERN.test(output)) {
+        return new Error("Unable to contact npm to validate access to @endo-ui/core. Configure an approved HTTP/HTTPS " +
+            "egress proxy through npm's proxy/https-proxy settings or HTTP_PROXY/HTTPS_PROXY. EndoUI " +
+            "keeps NPM_TOKEN scoped to registry.npmjs.org and does not use it with alternate package registries.");
     }
-    if (response.ok) {
-        let metadata;
+    return new Error(`npm access validation failed while checking @endo-ui/core (npm exit code ${result.exitCode ?? "unknown"}).`);
+}
+export async function validateNpmAccess(token, version, runner = runNpm) {
+    const directory = await mkdtemp(path.join(os.tmpdir(), "endoui-npm-access-"));
+    try {
+        await writeFile(path.join(directory, "package.json"), '{"private":true}\n', "utf8");
+        await writeFile(path.join(directory, ".npmrc"), `${NPMRC_REGION}\n`, {
+            encoding: "utf8",
+            mode: 0o600
+        });
+        let result;
+        try {
+            result = await runner(["view", `@endo-ui/core@${version}`, "version", "--json"], {
+                cwd: directory,
+                env: {
+                    ...process.env,
+                    NPM_TOKEN: token,
+                    NPM_CONFIG_CACHE: path.join(directory, "cache"),
+                    NPM_CONFIG_OFFLINE: "false",
+                    NPM_CONFIG_PREFER_OFFLINE: "false",
+                    NPM_CONFIG_PREFER_ONLINE: "true",
+                    NPM_CONFIG_UPDATE_NOTIFIER: "false"
+                }
+            });
+        }
+        catch {
+            throw new Error("Unable to start npm while validating access to @endo-ui/core.");
+        }
+        if (result.exitCode !== 0)
+            throw npmFailure(result, token);
+        const output = result.stdout.trim();
+        let reportedVersion = output;
         try {
-            metadata = await response.json();
+            reportedVersion = JSON.parse(output);
         }
         catch {
-            throw new Error("npm returned invalid package metadata for @endo-ui/core.");
+            // Older npm versions can return the plain value even when --json is supplied.
         }
-        if (!metadata.versions?.[version]) {
+        if (reportedVersion !== version) {
             throw new Error(`@endo-ui/core@${version} is not available to this npm token.`);
         }
-        return;
-    }
-    if (response.status === 401) {
-        throw new Error("The npm token is invalid, expired, or revoked.");
     }
-    if (response.status === 403 || response.status === 404) {
-        throw new Error("The npm token does not have read access to @endo-ui/core.");
+    finally {
+        await rm(directory, { recursive: true, force: true });
     }
-    throw new Error(`npm access validation failed with HTTP ${response.status}.`);
 }

package/bin/npmrc.js

@@ -3,12 +3,30 @@ import path from "node:path";
 export const NPMRC_BEGIN = "# BEGIN ENDOUI MANAGED CONFIG";
 export const NPMRC_END = "# END ENDOUI MANAGED CONFIG";
 export const NPMRC_REGION = `${NPMRC_BEGIN}\n@endo-ui:registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=\${NPM_TOKEN}\n${NPMRC_END}`;
+const NPMRC_REGISTRY_LINE = "@endo-ui:registry=https://registry.npmjs.org/";
+const NPMRC_TOKEN_LINE = "//registry.npmjs.org/:_authToken=${NPM_TOKEN}";
+function normalizedLines(content) {
+    return content.replace(/\r\n/g, "\n").split("\n").map(line => line.trim());
+}
+function hasEquivalentUnmanagedConfig(content) {
+    const lines = new Set(normalizedLines(content));
+    return lines.has(NPMRC_REGISTRY_LINE) && lines.has(NPMRC_TOKEN_LINE);
+}
+function newlineFor(content) {
+    return content.includes("\r\n") ? "\r\n" : "\n";
+}
+function regionFor(content) {
+    return NPMRC_REGION.replace(/\n/g, newlineFor(content));
+}
 export function updateNpmrcContent(content) {
     const begins = [...content.matchAll(new RegExp(NPMRC_BEGIN, "g"))];
     const ends = [...content.matchAll(new RegExp(NPMRC_END, "g"))];
     if (begins.length === 0 && ends.length === 0) {
-        const separator = content.length === 0 ? "" : content.endsWith("\n") ? "\n" : "\n\n";
-        return { content: `${content}${separator}${NPMRC_REGION}\n`, changed: true };
+        if (hasEquivalentUnmanagedConfig(content))
+            return { content, changed: false };
+        const newline = newlineFor(content);
+        const separator = content.length === 0 ? "" : content.endsWith(newline) ? newline : `${newline}${newline}`;
+        return { content: `${content}${separator}${regionFor(content)}${newline}`, changed: true };
     }
     if (begins.length !== 1 || ends.length !== 1 || begins[0].index >= ends[0].index) {
         throw new Error("The EndoUI managed .npmrc markers are malformed or ambiguous.");
@@ -16,10 +34,11 @@ export function updateNpmrcContent(content) {
     const start = begins[0].index;
     const end = ends[0].index + NPMRC_END.length;
     const existing = content.slice(start, end);
-    if (existing === NPMRC_REGION)
+    if (existing.replace(/\r\n/g, "\n") === NPMRC_REGION) {
         return { content, changed: false };
+    }
     return {
-        content: `${content.slice(0, start)}${NPMRC_REGION}${content.slice(end)}`,
+        content: `${content.slice(0, start)}${regionFor(content)}${content.slice(end)}`,
         changed: true
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endo-ui/license",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Developer and CI license activation for EndoUI.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {