requestshield 0.0.0-stage → 1.0.0-stg.276

package/src/integration-contract.mjs

@@ -0,0 +1,114 @@
+// @ts-check
+
+/** @typedef {{groupId: string, artifactId: string}} MavenArtifact */
+/** @typedef {{
+ * schemaVersion: 2, contractVersion: string,
+ * services: {challengeUrl: string},
+ * browser: {sdkVersion: string, scriptUrlVersion: string, scriptUrlLatest: string, integrity: string,
+ * tokenHeader: 'X-IntelliFend-Token', availableModes: Array<'manual' | 'seamless'>,
+ * cspAdditions: {scriptSrc: string[], connectSrc: string[], workerSrc: string[]}},
+ * backend: {sdkVersion: string, minJdk: number, mavenRepository: string,
+ * core: MavenArtifact, springBoot3: MavenArtifact & {framework: 'Spring Boot 3 MVC'}},
+ * documentation: {browserSdk: string, javaSdk: string, domainsAndCsp: string, releaseNotes?: string}
+ * }} IntegrationContract */
+
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const WASM_SCRIPT_SOURCE = "'wasm-unsafe-eval'";
+
+/** Shared by the CLI reader and customer-docs build checks. This module performs
+ * no I/O and includes no release data; customer-docs owns the selected releases.
+ * Schema 2 rejects extra fields so unreviewed content never reaches CLI output.
+ * @param {unknown} value
+ * @returns {{data: IntegrationContract}}
+ */
+export function validateIntegrationContract(value) {
+  const envelope = object(value, ['data']);
+  if (envelope.data && typeof envelope.data === 'object' && 'schemaVersion' in envelope.data && envelope.data.schemaVersion !== 2) {
+    throw new Error('Unsupported integration contract schema');
+  }
+  const data = object(envelope.data, ['schemaVersion', 'contractVersion', 'services', 'browser', 'backend', 'documentation']);
+  check(data.schemaVersion === 2);
+  version(data.contractVersion);
+
+  const services = object(data.services, ['challengeUrl']);
+  const challenge = publicUrl(services.challengeUrl);
+  const browser = object(data.browser, ['sdkVersion', 'scriptUrlVersion', 'scriptUrlLatest', 'integrity', 'tokenHeader', 'availableModes', 'cspAdditions']);
+  version(browser.sdkVersion);
+  const script = publicUrl(browser.scriptUrlVersion);
+  const latest = publicUrl(browser.scriptUrlLatest);
+  check(script.pathname === `/requestshield/v${browser.sdkVersion}/intellifend.js`);
+  check(latest.pathname === '/requestshield/latest/intellifend.js' && latest.origin === script.origin);
+  check(typeof browser.integrity === 'string' && /^sha384-[A-Za-z0-9+/]{64}$/.test(browser.integrity));
+  check(browser.tokenHeader === 'X-IntelliFend-Token');
+  const modes = stringList(browser.availableModes, 2);
+  check(modes.includes('manual') && modes.every(mode => mode === 'manual' || mode === 'seamless'));
+
+  const csp = object(browser.cspAdditions, ['scriptSrc', 'connectSrc', 'workerSrc']);
+  const scriptSources = stringList(csp.scriptSrc, 10);
+  for (const source of scriptSources) {
+    check(source === WASM_SCRIPT_SOURCE || publicUrl(source).origin === source);
+  }
+  // The shared additions cover latest as well as the pinned release.
+  check(scriptSources.includes(WASM_SCRIPT_SOURCE));
+  const connectSources = origins(csp.connectSrc);
+  check(scriptSources.includes(script.origin) && connectSources.includes(challenge.origin));
+  const workerSources = stringList(csp.workerSrc, 1);
+  check(workerSources.length === 1 && workerSources[0] === 'blob:');
+
+  const backend = object(data.backend, ['sdkVersion', 'minJdk', 'mavenRepository', 'core', 'springBoot3']);
+  version(backend.sdkVersion);
+  check(typeof backend.minJdk === 'number' && Number.isSafeInteger(backend.minJdk) && backend.minJdk >= 17 && backend.minJdk <= 100);
+  publicUrl(backend.mavenRepository);
+  const core = object(backend.core, ['groupId', 'artifactId']);
+  const starter = object(backend.springBoot3, ['groupId', 'artifactId', 'framework']);
+  for (const artifact of [core, starter]) {
+    check(typeof artifact.groupId === 'string' && /^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+$/.test(artifact.groupId) && artifact.groupId.length <= 200);
+    check(typeof artifact.artifactId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(artifact.artifactId));
+  }
+  check(starter.framework === 'Spring Boot 3 MVC');
+  const docs = object(data.documentation, ['browserSdk', 'javaSdk', 'domainsAndCsp'], ['releaseNotes']);
+  for (const url of Object.values(docs)) publicUrl(url);
+  return /** @type {{data: IntegrationContract}} */ (value);
+}
+
+/** @param {unknown} condition @returns {asserts condition} */
+function check(condition) {
+  if (!condition) throw new Error('Invalid integration contract');
+}
+
+/** @param {unknown} value @param {string[]} keys @param {string[]} [optionalKeys] @returns {Record<string, unknown>} */
+function object(value, keys, optionalKeys = []) {
+  check(value !== null && typeof value === 'object' && !Array.isArray(value));
+  const record = /** @type {Record<string, unknown>} */ (value);
+  check(keys.every(key => Object.hasOwn(record, key))
+    && Object.keys(record).every(key => keys.includes(key) || optionalKeys.includes(key)));
+  return record;
+}
+
+/** @param {unknown} value @returns {asserts value is string} */
+function version(value) {
+  check(typeof value === 'string' && value.length <= 64 && VERSION.test(value));
+}
+
+/** @param {unknown} value @returns {URL} */
+function publicUrl(value) {
+  check(typeof value === 'string' && value.length <= 2048 && /^[\x21-\x7e]+$/.test(value) && !/[?#\\]/.test(value));
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Invalid integration contract'); }
+  check(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash);
+  return url;
+}
+
+/** @param {unknown} value @param {number} maximum @returns {string[]} */
+function stringList(value, maximum) {
+  check(Array.isArray(value) && value.length >= 1 && value.length <= maximum);
+  check(value.every(item => typeof item === 'string') && new Set(value).size === value.length);
+  return /** @type {string[]} */ (value);
+}
+
+/** @param {unknown} value @returns {string[]} */
+function origins(value) {
+  const list = stringList(value, 10);
+  for (const item of list) check(publicUrl(item).origin === item);
+  return list;
+}

package/src/main.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { main } from "./entrypoint.mjs";
+
+void main();

package/src/oauth-client.mjs

@@ -0,0 +1,153 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+import { validateOAuthConfig, REQUESTED_OAUTH_SCOPES, validateBearerToken, validatedUrl } from "./config.mjs";
+
+/** @typedef {{accessToken: string, refreshToken: string, expiresAt: number, scopes: string[]}} OAuthCredentials */
+/** @typedef {{authorizationEndpoint: string, tokenEndpoint: string}} OAuthDiscovery */
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+export class OAuthClient {
+  /** @param {{config: import('./config.mjs').OAuthConfig, fetchImpl?: typeof fetch, now?: () => number, timeoutMs?: number}} options */
+  constructor({config, fetchImpl = fetch, now = Date.now, timeoutMs = 15_000}) {
+    this.config = validateOAuthConfig(config);
+    this.fetchImpl = fetchImpl;
+    this.now = now;
+    this.timeoutMs = timeoutMs;
+    /** @type {OAuthDiscovery | undefined} */
+    this.discovery = undefined;
+  }
+
+  /** @param {{signal?: AbortSignal}} [options] @returns {Promise<OAuthDiscovery>} */
+  async discover({signal} = {}) {
+    signal?.throwIfAborted();
+    if (this.discovery) return this.discovery;
+    const {body} = await this.#request(`${this.config.issuer}/.well-known/openid-configuration`, {method: "GET"}, signal);
+    if (body.issuer !== this.config.issuer) throw invalidResponse();
+    let authorizationEndpoint, tokenEndpoint;
+    try {
+      authorizationEndpoint = validatedUrl(body.authorization_endpoint, "authorization endpoint");
+      tokenEndpoint = validatedUrl(body.token_endpoint, "token endpoint");
+    } catch { throw invalidResponse(); }
+    const tokenUrl = new URL(tokenEndpoint);
+    if (tokenUrl.protocol !== "https:" || tokenUrl.origin !== new URL(this.config.issuer).origin) throw invalidResponse();
+    if (!Array.isArray(body.response_types_supported) || !body.response_types_supported.includes("code")
+      || !Array.isArray(body.code_challenge_methods_supported) || !body.code_challenge_methods_supported.includes("S256")) throw invalidResponse();
+    this.discovery = {authorizationEndpoint, tokenEndpoint};
+    return this.discovery;
+  }
+
+  /** @param {{code: string, verifier: string, redirectUri: string, signal?: AbortSignal}} args @returns {Promise<OAuthCredentials>} */
+  async exchangeCode({code, verifier, redirectUri, signal}) {
+    const {tokenEndpoint} = await this.discover({signal});
+    const {body} = await this.#request(tokenEndpoint, {
+      method: "POST",
+      body: new URLSearchParams({grant_type: "authorization_code", client_id: this.config.clientId, code, code_verifier: verifier, redirect_uri: redirectUri}),
+    }, signal);
+    return this.#credentials(body);
+  }
+
+  /** Public refresh tokens rotate. Never retry a dispatched exchange. @param {string} refreshToken @returns {Promise<OAuthCredentials>} */
+  async refresh(refreshToken) {
+    const {tokenEndpoint} = await this.discover();
+    try {
+      const {body} = await this.#request(tokenEndpoint, {
+        method: "POST",
+        body: new URLSearchParams({grant_type: "refresh_token", client_id: this.config.clientId, refresh_token: refreshToken}),
+      });
+      return this.#credentials(body);
+    } catch (error) {
+      if (error instanceof CliError && ["OAUTH_INVALID_GRANT", "OAUTH_REJECTED"].includes(error.code)) throw error;
+      throw new CliError("The refresh result is uncertain; run `requestshield login` again", {code: "OAUTH_REFRESH_UNCERTAIN", exitCode: 3});
+    }
+  }
+
+  /** @param {Record<string, unknown>} body @returns {OAuthCredentials} */
+  #credentials(body) {
+    let accessToken;
+    try { accessToken = validateBearerToken(body.access_token); } catch { throw invalidResponse(); }
+    const refreshToken = body.refresh_token;
+    if (typeof refreshToken !== "string" || !/^[\x21-\x7e]{1,16384}$/.test(refreshToken)
+      || typeof body.token_type !== "string" || body.token_type.toLowerCase() !== "bearer"
+      || typeof body.expires_in !== "number" || !Number.isSafeInteger(body.expires_in) || body.expires_in <= 0 || body.expires_in > 900
+      || typeof body.scope !== "string" || body.scope.length > 2048) throw invalidResponse();
+    const scopes = body.scope.split(" ");
+    if (new Set(scopes).size !== scopes.length || scopes.length !== REQUESTED_OAUTH_SCOPES.length
+      || !REQUESTED_OAUTH_SCOPES.every(scope => scopes.includes(scope))) throw invalidResponse();
+    return {accessToken, refreshToken, expiresAt: this.now() + body.expires_in * 1000, scopes};
+  }
+
+  /** @param {string} url @param {RequestInit} init @param {AbortSignal} [outerSignal] */
+  async #request(url, init, outerSignal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const timeout = setTimeout(abort, this.timeoutMs);
+    outerSignal?.addEventListener("abort", abort, {once: true});
+    if (outerSignal?.aborted) abort();
+    const signal = controller.signal;
+    let onAbort = () => {};
+    const cancelled = new Promise((_, reject) => {
+      onAbort = () => reject(new CliError("Could not connect to RequestShield sign-in. Check your connection and retry.", {code: "NETWORK_ERROR", exitCode: 7}));
+      signal.addEventListener("abort", onAbort, {once: true});
+      if (signal.aborted) onAbort();
+    });
+    try {
+      const operation = (async () => {
+        signal.throwIfAborted();
+        const response = await this.fetchImpl(url, {
+          ...init, signal, redirect: "error", credentials: "omit", cache: "no-store",
+          headers: {Accept: "application/json", ...(init.body ? {"Content-Type": "application/x-www-form-urlencoded"} : {})},
+        });
+        if (response.status >= 300 && response.status < 400) throw invalidResponse();
+        if (!response.body || Number(response.headers.get("content-length")) > MAX_BODY_BYTES) {
+          void response.body?.cancel().catch(() => {});
+          throw invalidResponse();
+        }
+        const reader = response.body.getReader();
+        const cancelBody = () => { void reader.cancel().catch(() => {}); };
+        signal.addEventListener("abort", cancelBody, {once: true});
+        if (signal.aborted) cancelBody();
+        const chunks = [];
+        let size = 0;
+        try {
+          while (true) {
+            const {done, value} = await reader.read();
+            if (done) break;
+            size += value.length;
+            if (size > MAX_BODY_BYTES) { void reader.cancel().catch(() => {}); throw invalidResponse(); }
+            chunks.push(value);
+          }
+        } finally { signal.removeEventListener("abort", cancelBody); reader.releaseLock(); }
+        /** @type {Record<string, unknown>} */
+        let body;
+        try {
+          body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(Buffer.concat(chunks)));
+          if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error();
+        } catch { throw invalidResponse(); }
+        if (!response.ok) {
+          if (body.error === "invalid_grant" || ["idp_refresh_token_invalid", "idp_authorization_code_invalid", "invalid_grant"].includes(String(body.error_type))) {
+            throw new CliError("Authorization was rejected; run `requestshield login` again", {code: "OAUTH_INVALID_GRANT", exitCode: 3});
+          }
+          if (response.status >= 400 && response.status < 500) {
+            throw new CliError("Sign-in was unsuccessful. Run `requestshield login` again; if the problem continues, contact support.", {code: "OAUTH_REJECTED", exitCode: 3});
+          }
+          throw new CliError("RequestShield sign-in is temporarily unavailable. Try again later.", {code: "NETWORK_ERROR", exitCode: 7});
+        }
+        return {body};
+      })();
+      return await Promise.race([operation, /** @type {Promise<never>} */ (cancelled)]);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw new CliError("Could not connect to RequestShield sign-in. Check your connection and retry.", {code: "NETWORK_ERROR", exitCode: 7});
+    } finally {
+      clearTimeout(timeout);
+      signal.removeEventListener("abort", onAbort);
+      outerSignal?.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+}
+
+function invalidResponse() {
+  return new CliError("Sign-in could not be completed. Try again; if the problem continues, contact support.", {code: "OAUTH_INVALID_RESPONSE", exitCode: 3});
+}

package/src/oauth-loopback.mjs

@@ -0,0 +1,120 @@
+// @ts-check
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { CliError } from "./errors.mjs";
+
+/** @typedef {{code: string}} AuthorizationResult */
+
+/** Bind before returning, so opening the browser cannot race port allocation.
+ * @param {{state: string, issuer: string, signal: AbortSignal}} options
+ */
+export async function createLoopbackReceiver({state, issuer, signal}) {
+  /** @type {(value: AuthorizationResult) => void} */
+  let resolveResult;
+  /** @type {(error: Error) => void} */
+  let rejectResult;
+  const result = new Promise((resolve, reject) => { resolveResult = resolve; rejectResult = reject; });
+  // A callback can arrive while the OS browser launcher is still returning.
+  void result.catch(() => {});
+  /** @type {import('node:http').ServerResponse | undefined} */
+  let pendingResponse;
+  let accepted = false;
+  let expectedHost = "";
+  const server = createServer({maxHeaderSize: 8192, requestTimeout: 5_000, headersTimeout: 5_000}, (request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Connection", "close");
+    const hostCount = request.rawHeaders.filter((_, i) => i % 2 === 0 && request.rawHeaders[i].toLowerCase() === "host").length;
+    if (request.method !== "GET" || request.headers.host !== expectedHost || hostCount !== 1
+      || request.headers["transfer-encoding"] || (request.headers["content-length"] && request.headers["content-length"] !== "0")) {
+      response.writeHead(400).end("Invalid authorization callback."); return;
+    }
+    const raw = request.url ?? "";
+    if (raw.length > 8192 || raw.split("?")[0] !== "/callback") {
+      response.writeHead(404).end("Not found."); return;
+    }
+    let url;
+    try { url = new URL(raw, `http://${expectedHost}`); } catch {
+      response.writeHead(400).end("Invalid authorization callback."); return;
+    }
+    const params = url.searchParams;
+    const suppliedState = params.get("state") ?? "";
+    const code = params.get("code");
+    const error = params.get("error");
+    if (url.hash || [...params.keys()].some(key => params.getAll(key).length !== 1)
+      || !equalState(suppliedState, state)
+      || (params.has("iss") && params.get("iss") !== issuer)
+      || (code === null) === (error === null)
+      || (code !== null && !/^[\x21-\x7e]{1,4096}$/.test(code))
+      || (error !== null && !/^[A-Za-z_]{1,128}$/.test(error))) {
+      response.writeHead(400).end("Invalid authorization callback."); return;
+    }
+    if (accepted) { response.writeHead(409).end("Authorization callback already received."); return; }
+    accepted = true;
+    if (error !== null) {
+      response.writeHead(400).end("Authorization was not completed. Return to your terminal.");
+      rejectResult(new CliError("Sign-in was denied or cancelled", {code: "SIGNIN_DENIED", exitCode: 3}));
+      return;
+    }
+    // Keep this response pending until token exchange AND protected storage succeed.
+    pendingResponse = response;
+    resolveResult({code: /** @type {string} */ (code)});
+  });
+  server.maxConnections = 8;
+  server.on("clientError", (_error, socket) => {
+    if (socket.writable) socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+    else socket.destroy();
+  });
+  const aborted = () => {
+    rejectResult(new CliError("Sign-in was cancelled or expired; run `requestshield login` again", {code: "SIGNIN_CANCELLED", exitCode: 3}));
+    if (pendingResponse && !pendingResponse.writableEnded) pendingResponse.writeHead(400).end("Sign-in was not completed. Return to your terminal.");
+    server.close();
+    server.closeAllConnections();
+  };
+  signal.addEventListener("abort", aborted, {once: true});
+  try {
+    if (signal.aborted) throw new Error();
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(undefined); });
+    });
+    if (signal.aborted) throw new Error();
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error();
+    expectedHost = `127.0.0.1:${address.port}`;
+  } catch {
+    signal.removeEventListener("abort", aborted);
+    server.close();
+    server.closeAllConnections();
+    throw new CliError("Could not start the local sign-in callback listener", {code: "SIGNIN_LISTENER_ERROR", exitCode: 3});
+  }
+  server.on("error", () => rejectResult(new CliError("The local sign-in listener failed", {code: "SIGNIN_LISTENER_ERROR", exitCode: 3})));
+  return {
+    redirectUri: `http://${expectedHost}/callback`,
+    result: /** @type {Promise<AuthorizationResult>} */ (result),
+    /** @param {boolean} success */
+    complete(success) {
+      if (!pendingResponse || pendingResponse.writableEnded) return;
+      pendingResponse.writeHead(success ? 200 : 400).end(success
+        ? "Signed in successfully. You may close this window and return to your terminal."
+        : "Sign-in was not completed. Return to your terminal.");
+    },
+    async close() {
+      signal.removeEventListener("abort", aborted);
+      if (!server.listening) return;
+      await new Promise(resolve => {
+        const timer = setTimeout(() => server.closeAllConnections(), 1000);
+        server.close(() => { clearTimeout(timer); resolve(undefined); });
+      });
+    },
+  };
+}
+
+/** @param {string} actual @param {string} expected */
+function equalState(actual, expected) {
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/src/package-profile.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+import packageJson from "../package.json" with { type: "json" };
+import { CliError } from "./errors.mjs";
+
+/** @typedef {'qat' | 'stg' | 'prod'} PackageProfile */
+
+/** Validate package metadata without reading service configuration or credentials.
+ * @param {unknown} value @returns {PackageProfile}
+ */
+export function validatePackageProfile(value) {
+  if (value !== "qat" && value !== "stg" && value !== "prod") {
+    throw new CliError("This RequestShield installation is invalid. Reinstall the CLI or contact support.", {
+      code: "INVALID_INSTALLATION", exitCode: 2,
+    });
+  }
+  return value;
+}
+
+/** The installed artifact fixes its runtime profile; no environment or cwd fallback. */
+export function getPackageProfile() {
+  const metadata = Reflect.get(packageJson, "requestshield");
+  return validatePackageProfile(metadata && typeof metadata === "object" && !Array.isArray(metadata)
+    ? Reflect.get(metadata, "profile") : undefined);
+}

package/src/private-path.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+import * as nativeFs from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+/** Establish access for the current OS user before writing any credential bytes.
+ * Callers own error translation; native errors must never reach command output.
+ * @param {string} file @param {boolean} directory
+ * @param {{platform?: NodeJS.Platform, fs?: Pick<typeof nativeFs, 'chmod'>}} [options]
+ */
+export async function protectPrivatePath(file, directory, options = {}) {
+  if ((options.platform ?? process.platform) !== "win32") {
+    await (options.fs ?? nativeFs).chmod(file, directory ? 0o700 : 0o600);
+    return;
+  }
+  // Static script, path in environment, current SID avoids domain lookup.
+  const script = [
+    '$ErrorActionPreference = "Stop"',
+    '$sessionSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User',
+    `$sessionAcl = New-Object System.Security.AccessControl.${directory ? "DirectorySecurity" : "FileSecurity"}`,
+    '$sessionAcl.SetOwner($sessionSid)',
+    '$sessionAcl.SetAccessRuleProtection($true, $false)',
+    directory
+      ? '$sessionRule = New-Object System.Security.AccessControl.FileSystemAccessRule($sessionSid, "FullControl", "ContainerInherit,ObjectInherit", "None", "Allow")'
+      : '$sessionRule = New-Object System.Security.AccessControl.FileSystemAccessRule($sessionSid, "FullControl", "Allow")',
+    '$sessionAcl.AddAccessRule($sessionRule)',
+    `[System.IO.${directory ? "Directory" : "File"}]::SetAccessControl($env:REQUESTSHIELD_SESSION_ACL_PATH, $sessionAcl)`,
+  ].join("\n");
+  await promisify(execFile)("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+    windowsHide: true, timeout: 10_000,
+    env: { SystemRoot: process.env.SystemRoot, PATH: process.env.PATH, REQUESTSHIELD_SESSION_ACL_PATH: file },
+  });
+}

package/src/secret-output.mjs

@@ -0,0 +1,121 @@
+// @ts-check
+import * as nativeFs from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.mjs";
+import { protectPrivatePath } from "./private-path.mjs";
+
+/** @typedef {{cwd?: string, platform?: NodeJS.Platform, fs?: Partial<typeof nativeFs>, protectPath?: (file: string, directory: boolean) => Promise<void>}} SecretOutputOptions */
+
+/** Validate syntax without touching the filesystem or exposing the supplied value.
+ * @param {string} value
+ */
+export function validateOutputPath(value) {
+  if (!value.trim() || value === "-" || /[\p{Cc}\p{Cs}]/u.test(value)) {
+    throw new CliError("--output requires a file path, not stdout or control characters.", {code: "INVALID_ARGUMENT", exitCode: 2});
+  }
+  return value;
+}
+
+/** A new, private file reserved before requesting a secret. Never replaces a file. */
+export class SecretOutputFile {
+  /** @param {string} file @param {SecretOutputOptions} [options] */
+  constructor(file, options = {}) {
+    this.file = path.resolve(options.cwd ?? process.cwd(), validateOutputPath(file));
+    this.platform = options.platform ?? process.platform;
+    this.fs = {...nativeFs, ...options.fs};
+    this.protectPath = options.protectPath ?? ((file, directory) => protectPrivatePath(file, directory, {platform: this.platform, fs: this.fs}));
+    /** @type {import('node:fs/promises').FileHandle | undefined} */
+    this.handle = undefined;
+    /** @type {import('node:fs').BigIntStats | undefined} */
+    this.identity = undefined;
+    this.completed = false;
+  }
+
+  async prepare() {
+    // Reject Windows devices and alternate data streams, including file aliases.
+    if (this.platform === "win32") {
+      const root = path.parse(this.file).root;
+      const parts = this.file.slice(root.length).split(/[\\/]/);
+      if (/^\\\\[?.]\\/.test(this.file) || parts.some(part => /[<>:"|?*]|[. ]$/.test(part)
+        || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
+        throw new CliError("--output must name a regular file.", {code: "INVALID_ARGUMENT", exitCode: 2});
+      }
+    }
+    try { await this.#prepareDirectories(); }
+    catch { throw prepareFailure(); }
+    try { this.handle = await this.fs.open(this.file, "wx", 0o600); }
+    catch (error) {
+      if (errorCode(error) === "EEXIST") {
+        throw new CliError("The output path already exists. Choose a new file; no application or secret request was sent.", {code: "OUTPUT_EXISTS", exitCode: 2});
+      }
+      throw prepareFailure();
+    }
+    try {
+      this.identity = await this.handle.stat({bigint: true});
+      await this.#assertOwnedFile();
+      await this.protectPath(this.file, false);
+      await this.#assertOwnedFile();
+      if (this.platform !== "win32" && process.platform !== "win32") {
+        const stat = await this.handle.stat();
+        if ((stat.mode & 0o777) !== 0o600 || stat.uid !== process.getuid?.()) throw new Error("permissions");
+      }
+    } catch { throw prepareFailure(); }
+  }
+
+  /** Only call with a validated API response. @param {string} appKey @param {string} apiSecret */
+  async commit(appKey, apiSecret) {
+    if (!this.handle) throw new Error("Output file is not reserved");
+    await this.#assertOwnedFile();
+    await this.handle.writeFile(`INTELLIFEND_REQUESTSHIELD_APP_KEY=${appKey}\nINTELLIFEND_REQUESTSHIELD_API_SECRET=${apiSecret}\n`, "utf8");
+    await this.handle.sync();
+    await this.#assertOwnedFile();
+    await this.handle.close();
+    this.handle = undefined;
+    this.completed = true;
+  }
+
+  /** Clean only the inode reserved by this invocation; never delete a replacement.
+   * @returns {Promise<boolean>} Whether no unfinished output remains at our path.
+   */
+  async cleanup() {
+    if (this.completed) return true;
+    const reserved = this.handle !== undefined;
+    try { await this.handle?.close(); } catch { /* Continue with best-effort removal. */ }
+    this.handle = undefined;
+    if (!this.identity) return !reserved;
+    try {
+      const current = await this.fs.lstat(this.file, {bigint: true});
+      if (!current.isFile() || current.isSymbolicLink() || current.dev !== this.identity.dev || current.ino !== this.identity.ino) return false;
+      await this.fs.unlink(this.file);
+      return true;
+    } catch (error) { return errorCode(error) === "ENOENT"; }
+  }
+
+  async #assertOwnedFile() {
+    const current = await this.fs.lstat(this.file, {bigint: true});
+    if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1n
+      || current.dev !== this.identity?.dev || current.ino !== this.identity?.ino) throw new Error("Output path changed");
+  }
+
+  async #prepareDirectories() {
+    const directory = path.dirname(this.file);
+    const root = path.parse(directory).root;
+    let current = root;
+    for (const part of directory.slice(root.length).split(path.sep).filter(Boolean)) {
+      current = path.join(current, part);
+      let created = false;
+      try { await this.fs.mkdir(current, {mode: 0o700}); created = true; }
+      catch (error) { if (errorCode(error) !== "EEXIST") throw error; }
+      const stat = await this.fs.lstat(current);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Invalid output directory");
+      // Do not change ACLs/modes on an existing user directory.
+      if (created) await this.protectPath(current, true);
+    }
+  }
+}
+
+/** @param {unknown} error */
+function errorCode(error) { return error && typeof error === "object" ? Reflect.get(error, "code") : undefined; }
+function prepareFailure() {
+  return new CliError("Could not prepare a private output file. Check the path and permissions and use ordinary directories without symbolic links or junctions. No application or secret request was sent.", {code: "OUTPUT_WRITE_FAILED", exitCode: 7});
+}

package/src/service-status-client.mjs

@@ -0,0 +1,87 @@
+// @ts-check
+
+export const SERVICE_TIMEOUT_MS = 5_000;
+const MAX_BODY_BYTES = 8 * 1024;
+
+/** @typedef {'management-api' | 'challenge-service'} Service */
+/** @typedef {'timeout' | 'network_error' | 'http_error' | 'invalid_response'} FailureReason */
+/** @typedef {{service: Service, url: string, status: 'ok' | 'failed', latencyMs: number, httpStatus: number | null, reason: FailureReason | null}} ServiceCheck */
+
+/** Public HTTP liveness only. A failure never hides the other service's result.
+ * @param {{apiUrl: string, challengeUrl: string, fetchImpl?: typeof fetch, timeoutMs?: number, clock?: () => number}} options
+ * @returns {Promise<ServiceCheck[]>}
+ */
+export function checkServices({apiUrl, challengeUrl, fetchImpl = fetch, timeoutMs = SERVICE_TIMEOUT_MS, clock = () => performance.now()}) {
+  return Promise.all([
+    checkService('management-api', new URL('/health', apiUrl).href, fetchImpl, timeoutMs, clock),
+    checkService('challenge-service', new URL('/health', challengeUrl).href, fetchImpl, timeoutMs, clock),
+  ]);
+}
+
+/** @param {Service} service @param {string} url @param {typeof fetch} fetchImpl
+ * @param {number} timeoutMs @param {() => number} clock @returns {Promise<ServiceCheck>}
+ */
+async function checkService(service, url, fetchImpl, timeoutMs, clock) {
+  const started = clock();
+  const controller = new AbortController();
+  /** @type {ReadableStreamDefaultReader<Uint8Array> | undefined} */
+  let reader;
+  /** @type {number | null} */
+  let httpStatus = null;
+  let expired = false;
+  /** @type {NodeJS.Timeout | undefined} */
+  let timer;
+  /** @type {Promise<FailureReason>} */
+  const deadline = new Promise(resolve => {
+    timer = setTimeout(() => {
+      expired = true;
+      controller.abort();
+      resolve('timeout');
+    }, timeoutMs);
+  });
+  try {
+    /** @returns {Promise<FailureReason | null>} */
+    const operation = async () => {
+      const response = await fetchImpl(url, {
+        method: 'GET', headers: {Accept: 'application/json'}, credentials: 'omit',
+        redirect: 'manual', cache: 'no-store', signal: controller.signal,
+      });
+      if (expired) { void response.body?.cancel().catch(() => {}); return 'timeout'; }
+      httpStatus = response.status;
+      if (response.status !== 200) {
+        void response.body?.cancel().catch(() => {});
+        return 'http_error';
+      }
+      const mediaType = response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+      if (!mediaType || !/^application\/(?:json|[a-z0-9!#$&^_.+-]+\+json)$/.test(mediaType)
+        || Number(response.headers.get('content-length')) > MAX_BODY_BYTES) {
+        void response.body?.cancel().catch(() => {});
+        return 'invalid_response';
+      }
+      const chunks = [];
+      let size = 0;
+      if (response.body) {
+        reader = response.body.getReader();
+        while (true) {
+          const {done, value} = await reader.read();
+          if (expired) return 'timeout';
+          if (done) break;
+          size += value.byteLength;
+          if (size > MAX_BODY_BYTES) return 'invalid_response';
+          chunks.push(value);
+        }
+      }
+      try {
+        const body = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(Buffer.concat(chunks)));
+        return body && typeof body === 'object' && !Array.isArray(body)
+          && body.status === 'ok' && body.service === service ? null : 'invalid_response';
+      } catch { return 'invalid_response'; }
+    };
+    const reason = await Promise.race([operation().catch(() => expired ? 'timeout' : /** @type {FailureReason} */ ('network_error')), deadline]);
+    return {service, url, status: reason === null ? 'ok' : 'failed', latencyMs: Math.max(0, Math.round(clock() - started)), httpStatus, reason};
+  } finally {
+    clearTimeout(timer);
+    if (reader) void reader.cancel().catch(() => {});
+    controller.abort();
+  }
+}