requestshield 0.0.0-stage → 1.0.0-stg.276

package/src/commands/update-check.mjs

@@ -0,0 +1,205 @@
+// @ts-check
+
+import readline from "node:readline/promises";
+import { spawn } from "node:child_process";
+import { stdin, stderr } from "node:process";
+import { CliError } from "../errors.mjs";
+import { rendererFor } from "../terminal.mjs";
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+
+/**
+ * @typedef {{ currentVersion: string, packageName: string, profile?: "qat" | "stg" | "prod", json?: boolean, yes?: boolean, log: (message: string) => void, warn?: (message: string) => void, fetchImpl?: typeof fetch, confirm?: (latestVersion: string) => Promise<boolean>, install?: (packageName: string, version: string) => Promise<void>, terminal?: import('../terminal.mjs').TerminalContext }} UpdateOptions
+ * @typedef {{ currentVersion: string, latestVersion: string | null, updateAvailable: boolean | null, action: "check" | "apply", outcome: "unavailable" | "up_to_date" | "available" | "installed" | "cancelled", target?: string }} UpdateResult
+ */
+
+/** @param {UpdateOptions} options */
+export async function checkForUpdate(options) {
+  const result = await inspectUpdate(options, "check");
+  printResult(result, options);
+  return result;
+}
+
+/** @param {UpdateOptions} options */
+export async function applyUpdate(options) {
+  const result = await inspectUpdate(options, "apply");
+  if (result.outcome !== "available" || result.latestVersion === null) {
+    printResult(result, options);
+    return result;
+  }
+
+  const warn = options.warn ?? ((message) => console.error(message));
+  const diagnostics = rendererFor(options, "stderr");
+  const target = `Update target: global npm installation of ${options.packageName}.`;
+  warn(options.json ? target : diagnostics.message("warning", target));
+  if (options.json && !options.yes) {
+    throw confirmationRequired();
+  }
+  const accepted = options.yes || await (options.confirm ?? confirmUpdate)(result.latestVersion);
+  if (!accepted) {
+    result.outcome = "cancelled";
+    printResult(result, options);
+    return result;
+  }
+
+  const progress = `Installing RequestShield ${result.latestVersion} globally with npm...`;
+  warn(options.json ? progress : diagnostics.message("info", progress));
+  await (options.install ?? installWithNpm)(options.packageName, result.latestVersion);
+  result.outcome = "installed";
+  printResult(result, options);
+  return result;
+}
+
+/** @param {UpdateOptions} options @param {"check" | "apply"} action @returns {Promise<UpdateResult>} */
+async function inspectUpdate(options, action) {
+  const profile = options.profile ?? "prod";
+  if (profile !== "prod") {
+    return { currentVersion: options.currentVersion, latestVersion: null, updateAvailable: null, action, outcome: "unavailable" };
+  }
+  const latestVersion = await fetchLatestVersion(options.packageName, options.fetchImpl ?? fetch);
+  const updateAvailable = compareVersions(latestVersion, options.currentVersion) > 0;
+  return {
+    currentVersion: options.currentVersion,
+    latestVersion,
+    updateAvailable,
+    action,
+    outcome: updateAvailable ? "available" : "up_to_date",
+    target: `global npm installation of ${options.packageName}`,
+  };
+}
+
+/** @param {UpdateResult} result @param {UpdateOptions} options */
+function printResult(result, options) {
+  if (options.json) {
+    options.log(JSON.stringify({ data: result }, null, 2));
+    return;
+  }
+  const renderer = rendererFor(options);
+  const sections = [renderer.heading("CLI update", "📥")];
+  if (result.outcome === "unavailable") {
+    sections.push(renderer.paragraph("Automatic updates are unavailable for this installation."));
+    options.log(sections.join("\n\n"));
+    return;
+  }
+  sections.push(renderer.fields([["Current version", result.currentVersion], ["Latest version", result.latestVersion ?? "unknown"]]));
+  if (result.outcome === "up_to_date") sections.push(renderer.message("success", "RequestShield is already up to date."));
+  if (result.outcome === "available") {
+    sections.push(renderer.message("info", "Run requestshield update apply to install the update."));
+    sections.push(renderer.paragraph(`Update target: ${result.target}.`));
+  }
+  if (result.outcome === "cancelled") sections.push(renderer.message("info", "Update cancelled."));
+  if (result.outcome === "installed") {
+    sections.push(renderer.message("success", `RequestShield ${result.latestVersion} was installed successfully (global npm installation).`));
+    sections.push(renderer.paragraph("Open a new terminal before running RequestShield again."));
+  }
+  options.log(sections.join("\n\n"));
+}
+
+/** @param {string} packageName @param {typeof fetch} fetchImpl */
+async function fetchLatestVersion(packageName, fetchImpl) {
+  const url = `${DEFAULT_REGISTRY}/${encodeURIComponent(packageName)}/latest`;
+  let response;
+  try {
+    response = await fetchImpl(url, { signal: AbortSignal.timeout(15_000) });
+  } catch {
+    throw new CliError("Could not check the latest RequestShield version. Check your connection and retry.", {
+      code: "UPDATE_CHECK_FAILED",
+      exitCode: 7,
+    });
+  }
+
+  if (!response.ok) {
+    throw new CliError(`Could not check the latest RequestShield version: HTTP ${response.status}`, {
+      code: "UPDATE_CHECK_FAILED",
+      exitCode: 7,
+    });
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new CliError("The npm registry returned an invalid RequestShield version", {
+      code: "INVALID_UPDATE_RESPONSE",
+    });
+  }
+  const version = body && typeof body === "object" ? Reflect.get(body, "version") : undefined;
+  if (typeof version !== "string" || !parseVersion(version)) {
+    throw new CliError("The npm registry returned an invalid RequestShield version", {
+      code: "INVALID_UPDATE_RESPONSE",
+    });
+  }
+  return version;
+}
+
+/** @param {string} latestVersion */
+async function confirmUpdate(latestVersion) {
+  if (!stdin.isTTY || !stderr.isTTY) throw confirmationRequired();
+  const prompt = readline.createInterface({ input: stdin, output: stderr });
+  try {
+    const answer = await prompt.question(`Install RequestShield ${latestVersion} globally with npm? (y/N): `);
+    return answer.trim().toLowerCase() === "y";
+  } finally {
+    prompt.close();
+  }
+}
+
+function confirmationRequired() {
+  return new CliError("Installing an update requires confirmation. Use an interactive terminal or pass --yes to requestshield update apply.", {
+    code: "UPDATE_CONFIRMATION_REQUIRED",
+    exitCode: 2,
+  });
+}
+
+/** @param {string} packageName @param {string} version */
+async function installWithNpm(packageName, version) {
+  await new Promise((resolve, reject) => {
+    const child = spawn("npm", ["install", "--global", `${packageName}@${version}`], {
+      shell: process.platform === "win32",
+      // npm's output is diagnostic. Keep command stdout available for JSON.
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    child.stdout?.pipe(stderr, { end: false });
+    child.stderr?.pipe(stderr, { end: false });
+    child.once("error", () => {
+      reject(new CliError("Could not start npm. Check that npm is installed and available.", {
+        code: "UPDATE_FAILED",
+        exitCode: 1,
+      }));
+    });
+    child.once("exit", (code) => {
+      if (code === 0) resolve(undefined);
+      else reject(new CliError(`npm update failed with exit code ${code ?? "unknown"}`, {
+        code: "UPDATE_FAILED",
+        exitCode: 1,
+      }));
+    });
+  });
+}
+
+/** @param {string} left @param {string} right */
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b) throw new CliError("RequestShield has an invalid semantic version");
+  for (let index = 0; index < 3; index++) {
+    if (a.numbers[index] !== b.numbers[index]) return a.numbers[index] - b.numbers[index];
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === undefined) return 1;
+  if (b.prerelease === undefined) return -1;
+  return a.prerelease.localeCompare(b.prerelease, "en", { numeric: true });
+}
+
+/** @param {string} value */
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+  if (!match) return undefined;
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4],
+  };
+}
+
+export { compareVersions };

package/src/commands/usage.mjs

@@ -0,0 +1,72 @@
+// @ts-check
+import { validateAppKey } from "../args.mjs";
+import { utcTimestamp, validateUsageRange } from "../usage-time.mjs";
+import { rendererFor } from "../terminal.mjs";
+import { invalidResponse, responseObject } from "./application-response.mjs";
+import { printData } from "./output.mjs";
+
+const DAY_MS = 86_400_000;
+const OPERATIONS = /** @type {const} */ (["challenge_create", "challenge_verify", "token_consume"]);
+const OPERATION_LABELS = ["Challenge requests", "Challenge verification", "Token verification"];
+
+/** @typedef {{requests: number, success: number, rejected: number, error: number}} OperationCounts */
+
+/** @param {{appKey: string, json?: boolean, from?: string, to?: string}} options
+ * @param {{api: {getUsage(token: string, appKey: string, range: {from?: string, to?: string}): Promise<{body: unknown}>}, sessions: {loadToken(): Promise<string>}, log(message: string): void, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function showUsage(options, deps) {
+  validateAppKey(options.appKey);
+  const range = validateUsageRange(options);
+  const token = await deps.sessions.loadToken();
+  const result = await deps.api.getUsage(token, options.appKey, range);
+  const data = parseUsageResponse(result.body, options);
+  if (options.json) printData(data, deps);
+  else {
+    const renderer = rendererFor(deps);
+    const sections = [renderer.heading("Application usage"), renderer.fields([
+      ["App Key", data.appKey], ["From", data.from], ["To", data.to],
+    ]), renderer.table(["OPERATION", "REQUESTS", "SUCCESS", "REJECTED", "ERROR"], OPERATIONS.map((operation, index) => {
+      const counts = data.operations[operation];
+      return [OPERATION_LABELS[index], ...[counts.requests, counts.success, counts.rejected, counts.error].map(String)];
+    }))];
+    if (OPERATIONS.every(operation => data.operations[operation].requests === 0)) sections.push(renderer.paragraph("No recorded requests."));
+    sections.push(renderer.paragraph("Approximate monitoring counts. Data may be delayed or incomplete; these are not billing totals."),
+      renderer.paragraph("Usage reports cover API v2 requests only. API v1 activity is not included."),
+      renderer.paragraph("Success: challenges created, successful verifies with tokens issued, and tokens accepted for the first time. Retries count separately; verifies are not unique challenges. Unattributed requests are excluded."));
+    deps.log(sections.join("\n\n"));
+  }
+  return data;
+}
+
+/** Build an allowlisted response, never forwarding unexpected server fields.
+ * @param {unknown} body @param {{appKey: string, from?: string, to?: string}} options
+ */
+export function parseUsageResponse(body, options) {
+  const data = responseObject(responseObject(body).data);
+  const from = utcTimestamp(data.from), to = utcTimestamp(data.to);
+  if (data.appKey !== options.appKey || data.approximate !== true || from === undefined || to === undefined || from >= to || to - from > 7 * DAY_MS) throw invalidUsage();
+  if (options.from !== undefined && (from !== utcTimestamp(options.from) || to !== utcTimestamp(options.to))) throw invalidUsage();
+  if (options.from === undefined && to - from !== DAY_MS) throw invalidUsage();
+  const operations = responseObject(data.operations);
+  if (Object.keys(operations).length !== OPERATIONS.length || OPERATIONS.some(operation => !Object.hasOwn(operations, operation))) throw invalidUsage();
+  return {
+    appKey: options.appKey, from: new Date(from).toISOString(), to: new Date(to).toISOString(), approximate: /** @type {const} */ (true),
+    operations: {
+      challenge_create: parseCounts(operations.challenge_create),
+      challenge_verify: parseCounts(operations.challenge_verify),
+      token_consume: parseCounts(operations.token_consume),
+    },
+  };
+}
+
+/** @param {unknown} value @returns {OperationCounts} */
+function parseCounts(value) {
+  const counts = responseObject(value);
+  const {requests, success, rejected, error} = counts;
+  if (!validCount(requests) || !validCount(success) || !validCount(rejected) || !validCount(error) || requests !== success + rejected + error) throw invalidUsage();
+  return {requests, success, rejected, error};
+}
+
+/** @param {unknown} value @returns {value is number} */
+function validCount(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER; }
+function invalidUsage() { return invalidResponse("The usage response did not match the requested app, time range or count schema"); }

package/src/config.mjs

@@ -0,0 +1,200 @@
+// @ts-check
+import { readFileSync } from "node:fs";
+import { parseEnv } from "node:util";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.mjs";
+import { getPackageProfile } from "./package-profile.mjs";
+
+/** @typedef {'qat' | 'stg' | 'prod'} Profile */
+const PROFILES = new Set(["qat", "stg", "prod"]);
+const CONFIG_KEYS = new Set(["API_URL", "CHALLENGE_URL", "DOCS_URL", "OAUTH_ISSUER", "OAUTH_CLIENT_ID", "OAUTH_AUTHORIZATION_ISSUER"]);
+
+export const DEFAULT_MAVEN_REPOSITORY =
+    "https://sdk.intellifend.com/packages/maven";
+
+export const DEFAULT_BROWSER_SCRIPT_URL =
+    "https://intellifend.ai/intellifend.js";
+
+export const REQUESTED_OAUTH_SCOPES = Object.freeze([
+  "offline_access",
+  "theair:applications:read",
+  "theair:applications:write",
+  "theair:secrets:read",
+  "theair:secrets:write",
+]);
+
+/** @typedef {{issuer: string, clientId: string, apiUrl: string}} OAuthConfig */
+
+/** Read only the selected package file; never load settings into process.env.
+ * @param {Profile} [profile] @returns {OAuthConfig}
+ */
+export function getOAuthConfig(profile = "prod") {
+  const values = readProfileConfig(profile);
+  if (!values.OAUTH_ISSUER || !values.OAUTH_CLIENT_ID) {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+  return validateOAuthConfig({issuer: values.OAUTH_ISSUER, clientId: values.OAUTH_CLIENT_ID, apiUrl: configuredApiUrl(values, profile)});
+}
+
+/** Callback-only issuer pin; it never selects discovery or token endpoints.
+ * @param {Profile | undefined} profile @param {string} fallbackIssuer
+ */
+export function getAuthorizationIssuer(profile, fallbackIssuer) {
+  const value = readProfileConfig(profile ?? "prod").OAUTH_AUTHORIZATION_ISSUER;
+  return value ? validateAuthorizationIssuer(value) : fallbackIssuer;
+}
+
+/** Preserve exact provider identifiers, including non-URL Stytch project IDs.
+ * @param {unknown} value @returns {string}
+ */
+export function validateAuthorizationIssuer(value) {
+  if (typeof value !== "string" || !/^[\x21-\x7e]{1,2048}$/.test(value)) {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+  return value;
+}
+
+/** Validate injected OAuth clients as well as file-based configuration.
+ * @param {OAuthConfig} config @returns {OAuthConfig}
+ */
+export function validateOAuthConfig({issuer: issuerValue, clientId, apiUrl}) {
+  const issuer = validatedUrl(issuerValue, "OAUTH_ISSUER");
+  if (new URL(issuer).protocol !== "https:") throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  if (typeof clientId !== "string" || !/^[A-Za-z0-9._~-]{1,256}$/.test(clientId)) {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+  return {issuer, clientId, apiUrl: validatedUrl(apiUrl, "API_URL")};
+}
+
+/** Shared API selection for signin binding and every authenticated command.
+ * @param {Profile} [profile]
+ */
+export function getApiUrl(profile = "prod") {
+  return configuredApiUrl(readProfileConfig(profile), profile);
+}
+
+/** Validate both public liveness targets before either request is dispatched.
+ * OAuth and documentation settings are not needed. @param {Profile} [profile]
+ */
+export function getServiceConfig(profile = "prod") {
+  let values;
+  try { values = readProfileConfig(profile); }
+  catch (error) {
+    throw new CliError(error instanceof CliError ? error.message : "Cannot read the RequestShield service configuration", {code: "SERVICE_CONFIG_INVALID", exitCode: 2});
+  }
+  return {apiUrl: validateServiceUrl(values.API_URL, "API_URL"), challengeUrl: validateServiceUrl(values.CHALLENGE_URL, "CHALLENGE_URL")};
+}
+
+/** @param {unknown} value @param {'API_URL' | 'CHALLENGE_URL'} name */
+export function validateServiceUrl(value, name) {
+  try {
+    if (typeof value !== "string" || !/^[\x21-\x7e]+$/.test(value) || /[\\?#]/.test(value)) throw new Error();
+    return validatedUrl(value, name);
+  } catch {
+    throw new CliError("Service status is unavailable. Update the CLI or contact support.", {code: "SERVICE_CONFIG_INVALID", exitCode: 2});
+  }
+}
+
+/** Public documentation selection is independent of API and OAuth settings.
+ * @param {Profile} [profile]
+ */
+export function getDocsUrl(profile = "prod") {
+  let values;
+  try { values = readProfileConfig(profile); }
+  catch (error) {
+    throw new CliError(error instanceof CliError ? error.message : "Cannot read the RequestShield documentation configuration", {code: "CONTRACT_CONFIG_INVALID", exitCode: 2});
+  }
+  if (!values.DOCS_URL) {
+    throw new CliError("Integration settings are unavailable. Update the CLI or contact support.", {code: "CONTRACT_CONFIG_INVALID", exitCode: 2});
+  }
+  return validateDocsUrl(values.DOCS_URL);
+}
+
+/** @param {unknown} value */
+export function validateDocsUrl(value) {
+  try {
+    if (typeof value !== "string" || !/^[\x21-\x7e]+$/.test(value) || /[\\?#]/.test(value)) throw new Error();
+    return validatedUrl(value, "DOCS_URL").replace(/\/+$/, "");
+  }
+  catch {
+    throw new CliError("Integration settings are unavailable. Update the CLI or contact support.", {code: "CONTRACT_CONFIG_INVALID", exitCode: 2});
+  }
+}
+
+/** @param {Record<string, string | undefined>} values @param {Profile} profile */
+function configuredApiUrl(values, profile) {
+  if (!values.API_URL) {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+  return validatedUrl(values.API_URL, "API_URL");
+}
+
+/** @param {Profile} [profile] */
+export function getCommandName(profile = getPackageProfile()) {
+  const packageProfile = getPackageProfile();
+  validateProfile(profile);
+  return profile === packageProfile ? "requestshield" : `requestshield-${profile}`;
+}
+
+/** Keep suggested commands runnable from either supported source directory.
+ * @param {Profile} [profile] @param {string} [cwd]
+ */
+export function getCommandInvocation(profile = getPackageProfile(), cwd = process.cwd()) {
+  const command = getCommandName(profile);
+  if (command === "requestshield") return command;
+  const packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+  return path.resolve(cwd) === packageRoot ? `npx --prefix ./dev ${command}` : `npx ${command}`;
+}
+
+/** @param {Profile} profile */
+function validateProfile(profile) {
+  if (!PROFILES.has(profile)) throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+}
+
+/** @param {Profile} profile @returns {Record<string, string | undefined>} */
+function readProfileConfig(profile) {
+  validateProfile(profile);
+  let values;
+  try {
+    values = parseEnv(readFileSync(new URL(`../config/.env.${profile}`, import.meta.url), "utf8"));
+  } catch {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+  if (Object.keys(values).some(key => !CONFIG_KEYS.has(key))) {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+  return values;
+}
+
+/** @param {unknown} value @returns {string} */
+export function validateBearerToken(value) {
+  if (typeof value !== "string" || value.length > 16_384 || !/^[A-Za-z0-9._~+/-]+=*$/.test(value)) {
+    throw new CliError("The access token is invalid; run `requestshield login` again", {
+      code: "INVALID_ACCESS_TOKEN", exitCode: 3,
+    });
+  }
+  return value;
+}
+
+/** @param {URL} url */
+export function isLoopbackUrl(url) {
+  return url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+
+/** @param {unknown} value @param {string} name */
+export function validatedUrl(value, name) {
+  try {
+    if (typeof value !== "string" || value.length > 2048 || /\s/.test(value)) throw new Error();
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== "https:" && !isLoopbackUrl(url))) throw new Error();
+    return url.href.replace(/\/$/, "");
+  } catch {
+    throw invalidConfig("RequestShield sign-in is unavailable. Update the CLI and try again; if the problem continues, contact support.");
+  }
+}
+
+/** @param {string} message */
+function invalidConfig(message) {
+  return new CliError(message, { code: "OAUTH_CONFIG_INVALID", exitCode: 2 });
+}

package/src/entrypoint.mjs

@@ -0,0 +1,44 @@
+// @ts-check
+import { run } from "./cli.mjs";
+import { CliError } from "./errors.mjs";
+import { CommandCompletion } from "./command-completion.mjs";
+import { getCommandInvocation, getCommandName } from "./config.mjs";
+import { rendererFor, resolveTerminal } from "./terminal.mjs";
+import { getPackageProfile } from "./package-profile.mjs";
+
+/** Render exactly one result document on JSON failures. Unknown failures are redacted.
+ * @param {string[]} argv @param {Parameters<typeof run>[1]} [deps] */
+export async function execute(argv, deps = {}) {
+  let command = "requestshield";
+  let invocation = command;
+  try {
+    const profile = deps.profile ?? getPackageProfile();
+    command = getCommandName(profile);
+    invocation = getCommandInvocation(profile);
+    const result = await run(argv, {...deps, profile});
+    return result instanceof CommandCompletion ? result.exitCode : 0;
+  } catch (error) {
+    const known = error instanceof CliError;
+    const message = (known ? error.message : "The command failed unexpectedly. Please try again.")
+      .replaceAll("`requestshield login`", `\`${invocation} login\``)
+      .replaceAll("`requestshield logout`", `\`${invocation} logout\``)
+      .replaceAll("Usage: requestshield ", `Usage: ${invocation} `)
+      .replace(/^  requestshield /gm, `  ${invocation} `);
+    const code = known ? error.code : "CLI_ERROR";
+    if (argv.includes("--json")) (deps.log ?? console.log)(JSON.stringify({error: {code, message}}, null, 2));
+    else {
+      const renderer = rendererFor({terminal: resolveTerminal(deps)}, "stderr");
+      (deps.warn ?? console.error)([
+        renderer.heading(command),
+        renderer.message("error", message),
+        renderer.muted(`Code: ${code}`),
+      ].join("\n"));
+    }
+    return known ? error.exitCode : 1;
+  }
+}
+
+/** @param {import('./config.mjs').Profile} [profile] */
+export async function main(profile) {
+  process.exitCode = await execute(process.argv.slice(2), {profile});
+}

package/src/errors.mjs

@@ -0,0 +1,16 @@
+// @ts-check
+
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, exitCode?: number, httpStatus?: number, apiErrorCode?: string }} [options]
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = options.code ?? "CLI_ERROR";
+    this.exitCode = options.exitCode ?? 1;
+    this.httpStatus = options.httpStatus;
+    this.apiErrorCode = options.apiErrorCode;
+  }
+}

package/src/integration-contract-client.mjs

@@ -0,0 +1,85 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+import { validateDocsUrl } from "./config.mjs";
+import { validateIntegrationContract } from "./integration-contract.mjs";
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+/** Fetch only public metadata. Never attach OAuth credentials or use Management APIs. */
+export class IntegrationContractClient {
+  /** @param {{docsUrl: string, fetchImpl?: typeof fetch, timeoutMs?: number}} options */
+  constructor({docsUrl, fetchImpl = fetch, timeoutMs = 15_000}) {
+    this.url = `${validateDocsUrl(docsUrl)}/integration-contract.json`;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async getContract() {
+    const controller = new AbortController();
+    /** @type {ReadableStreamDefaultReader<Uint8Array> | undefined} */
+    let reader;
+    let expired = false;
+    /** @type {NodeJS.Timeout | undefined} */
+    let timer;
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        expired = true;
+        controller.abort();
+        reject(timeout());
+      }, this.timeoutMs);
+    });
+    try {
+      const operation = (async () => {
+        const response = await this.fetchImpl(this.url, {
+          method: "GET", headers: {Accept: "application/json"},
+          credentials: "omit", redirect: "error", cache: "no-store", signal: controller.signal,
+        });
+        if (expired) { void response.body?.cancel().catch(() => {}); throw timeout(); }
+        if (!response.ok) {
+          void response.body?.cancel().catch(() => {});
+          throw new CliError(response.status === 404 ? "The public integration contract is not available yet (HTTP 404)." : `The public integration contract request failed: HTTP ${response.status}.`, {code: response.status === 404 ? "CONTRACT_NOT_PUBLISHED" : "CONTRACT_FETCH_FAILED", exitCode: 1, httpStatus: response.status});
+        }
+        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(() => {});
+          throw invalidResponse();
+        }
+        const chunks = [];
+        let size = 0;
+        if (response.body) {
+          reader = response.body.getReader();
+          while (true) {
+            const {done, value} = await reader.read();
+            if (expired) throw timeout();
+            if (done) break;
+            size += value.byteLength;
+            if (size > MAX_BODY_BYTES) throw invalidResponse();
+            chunks.push(value);
+          }
+        }
+        try {
+          const body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(Buffer.concat(chunks)));
+          return validateIntegrationContract(body);
+        } catch (error) {
+          if (error instanceof Error && error.message === 'Unsupported integration contract schema') {
+            throw new CliError('Unsupported integration contract schema. Update the RequestShield CLI and try again. If the problem continues, contact support.', {code: 'CONTRACT_INVALID', exitCode: 1});
+          }
+          throw invalidResponse();
+        }
+      })();
+      return await Promise.race([operation, /** @type {Promise<never>} */ (deadline)]);
+    } catch (error) {
+      if (expired) throw timeout();
+      if (error instanceof CliError) throw error;
+      throw new CliError("Could not retrieve the public integration contract. Check connectivity and try again.", {code: "CONTRACT_FETCH_FAILED", exitCode: 1});
+    } finally {
+      clearTimeout(timer);
+      if (reader) void reader.cancel().catch(() => {});
+      controller.abort();
+    }
+  }
+}
+
+function timeout() { return new CliError("The public integration contract request timed out. Check connectivity and try again.", {code: "CONTRACT_FETCH_FAILED", exitCode: 1}); }
+function invalidResponse() { return new CliError("The public integration contract is invalid or too large. Try again; if the problem continues, contact support.", {code: "CONTRACT_INVALID", exitCode: 1}); }