requestshield 0.1.5 → 0.1.6

package/src/commands/mutation-support.mjs

@@ -0,0 +1,110 @@
+// @ts-check
+import { randomUUID } from "node:crypto";
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { CliError } from "../errors.mjs";
+import { getCommandInvocation } from "../config.mjs";
+import { APPLICATION_STATUSES, invalidResponse, responseObject } from "./application-response.mjs";
+
+/** @typedef {{body: unknown, status?: number, replayed?: boolean}} MutationResponse */
+/** @typedef {{log: (message: string) => void, warn?: (message: string) => void, profile?: import('../config.mjs').Profile, confirm?: () => Promise<boolean>}} CommandOutput */
+
+/** @param {string | undefined} supplied */
+export function mutationKey(supplied) {
+  const key = supplied ?? randomUUID();
+  if (!/^[A-Za-z0-9._~-]{1,128}$/.test(key)) {
+    throw new CliError("Idempotency key must contain 1-128 letters, numbers, '.', '_', '~', or '-'", {code: "INVALID_IDEMPOTENCY_KEY", exitCode: 2});
+  }
+  return key;
+}
+
+/** @param {{yes?: boolean}} options @param {CommandOutput} deps @param {string} prompt @param {string} word */
+export async function confirmAction(options, deps, prompt, word) {
+  if (options.yes) return;
+  let accepted;
+  if (deps.confirm) accepted = await deps.confirm();
+  else {
+    if (!stdin.isTTY || !stdout.isTTY) {
+      throw new CliError("This action requires confirmation; use --yes in a non-interactive terminal", {code: "CONFIRMATION_REQUIRED", exitCode: 2});
+    }
+    const terminal = readline.createInterface({input: stdin, output: stdout});
+    try { accepted = await terminal.question(`${prompt} Type ${word} to continue: `) === word; }
+    finally { terminal.close(); }
+  }
+  if (!accepted) throw new CliError("Action cancelled", {code: "CANCELLED", exitCode: 2});
+}
+
+/** The caller wraps dispatch and response validation, never session loading.
+ * @template T @param {string} idempotencyKey @param {CommandOutput} deps @param {() => Promise<T>} operation @returns {Promise<T>}
+ */
+export async function withMutationRecovery(idempotencyKey, deps, operation) {
+  // Print before dispatch so interruption cannot hide the identity needed to retry.
+  (deps.warn ?? deps.log)(`Idempotency key: ${idempotencyKey}`);
+  try { return await operation(); }
+  catch (error) {
+    const status = error instanceof CliError ? Reflect.get(error, "httpStatus") : undefined;
+    const uncertain = !(error instanceof CliError)
+      || ["NETWORK_ERROR", "REQUEST_TIMEOUT", "INVALID_RESPONSE"].includes(error.code)
+      || (error.code === "API_ERROR" && (typeof status !== "number" || status >= 500));
+    if (!uncertain) throw error;
+    throw new CliError(
+      `The mutation result could not be confirmed; it may have completed. Retry the same command and arguments with --idempotency-key ${idempotencyKey} within seven days of the original attempt. Do not use a new key to retry. After seven days, inspect the application before taking further action.`,
+      {code: "MUTATION_UNCERTAIN", exitCode: 7},
+    );
+  }
+}
+
+/** @param {MutationResponse} result @param {number} expectedStatus */
+export function validateHttpStatus(result, expectedStatus) {
+  if (result.status !== undefined && result.status !== expectedStatus) {
+    throw invalidResponse("The API returned an unexpected success status");
+  }
+}
+
+/** @param {MutationResponse} result @param {number} expectedStatus @param {string} [requestedAppKey] */
+export function parseIssuance(result, expectedStatus, requestedAppKey) {
+  validateHttpStatus(result, expectedStatus);
+  const {appKey, status, apiSecret} = responseObject(result.body);
+  if (typeof appKey !== "string" || !/^[A-Za-z0-9._~-]{1,128}$/.test(appKey)
+    || (requestedAppKey !== undefined && appKey !== requestedAppKey)
+    || typeof status !== "string" || !APPLICATION_STATUSES.has(status)
+    || (apiSecret !== null && !isApiSecret(apiSecret))
+    || (result.replayed === true && apiSecret !== null)
+    || (result.replayed === false && apiSecret === null)) {
+    throw invalidResponse("The issuance response did not match the expected application, status and secret contract");
+  }
+  return {appKey, status, apiSecret};
+}
+
+/** @param {unknown} value @returns {value is string} */
+export function isApiSecret(value) {
+  return typeof value === "string" && /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(value);
+}
+
+/** @param {{appKey: string, status: string, apiSecret: string | null}} issuance @param {CommandOutput} deps */
+export function printIssuance(issuance, deps) {
+  const invocation = getCommandInvocation(deps.profile);
+  deps.log(`App Key: ${issuance.appKey}`);
+  deps.log(`Status: ${issuance.status}`);
+  if (issuance.apiSecret === null) {
+    deps.log(`This is an idempotency replay; the API did not return a secret. Run \`${invocation} keys reveal ${issuance.appKey}\` to retrieve the current active secret.`);
+  } else {
+    deps.log(`Secret Key: ${issuance.apiSecret}`);
+    deps.log("Store this secret in your backend secret manager. The CLI did not save it.");
+  }
+  deps.log("Configuration publication is asynchronous; this response does not confirm propagation.");
+}
+
+/** @param {MutationResponse} result */
+export function parseAccepted(result) {
+  validateHttpStatus(result, 202);
+  if (responseObject(result.body).status !== "accepted") {
+    throw invalidResponse("The mutation response did not acknowledge acceptance");
+  }
+}
+
+/** @param {string} action @param {string} appKey @param {CommandOutput} deps */
+export function printAccepted(action, appKey, deps) {
+  deps.log(`${action} accepted for ${appKey}. Configuration publication is asynchronous.`);
+  deps.log(`Run \`${getCommandInvocation(deps.profile)} apps get ${appKey}\` to check the current application status.`);
+}

package/src/commands/secret-commands.mjs

@@ -0,0 +1,45 @@
+// @ts-check
+import { invalidResponse, responseObject } from "./application-response.mjs";
+import { confirmAction, isApiSecret, mutationKey, parseAccepted, parseIssuance, printAccepted, printIssuance, validateHttpStatus, withMutationRecovery } from "./mutation-support.mjs";
+
+/** @typedef {import('./mutation-support.mjs').MutationResponse} MutationResponse */
+/** @typedef {import('./mutation-support.mjs').CommandOutput & {sessions: {loadToken(): Promise<string>}}} Dependencies */
+/** @typedef {{appKey: string, yes?: boolean, idempotencyKey?: string}} MutationOptions */
+
+/** @param {MutationOptions} options
+ * @param {Dependencies & {api: {rotateSecret(token: string, appKey: string, options: {idempotencyKey: string}): Promise<MutationResponse>}}} deps
+ */
+export async function rotateSecret(options, deps) {
+  await confirmAction(options, deps, `Replace the current secret for ${options.appKey}? Existing backend configuration will need the new secret.`, "ROTATE");
+  const idempotencyKey = mutationKey(options.idempotencyKey);
+  const token = await deps.sessions.loadToken();
+  const issuance = await withMutationRecovery(idempotencyKey, deps, async () =>
+    parseIssuance(await deps.api.rotateSecret(token, options.appKey, {idempotencyKey}), 200, options.appKey));
+  printIssuance(issuance, deps);
+}
+
+/** @param {{appKey: string, yes?: boolean}} options
+ * @param {Dependencies & {api: {revealSecret(token: string, appKey: string): Promise<MutationResponse>}}} deps
+ */
+export async function revealSecret(options, deps) {
+  await confirmAction(options, deps, `Display the current API secret for ${options.appKey} in this terminal?`, "REVEAL");
+  const token = await deps.sessions.loadToken();
+  const result = await deps.api.revealSecret(token, options.appKey);
+  validateHttpStatus(result, 200);
+  const {apiSecret} = responseObject(result.body);
+  if (!isApiSecret(apiSecret)) throw invalidResponse("The reveal response did not contain a valid API secret");
+  deps.log(`Secret Key: ${apiSecret}`);
+  deps.log("Store this secret in your backend secret manager. The CLI did not save it.");
+}
+
+/** @param {MutationOptions} options
+ * @param {Dependencies & {api: {revokeSecret(token: string, appKey: string, options: {idempotencyKey: string}): Promise<MutationResponse>}}} deps
+ */
+export async function revokeSecret(options, deps) {
+  await confirmAction(options, deps, `Revoke the current API secret for ${options.appKey}?`, "REVOKE");
+  const idempotencyKey = mutationKey(options.idempotencyKey);
+  const token = await deps.sessions.loadToken();
+  await withMutationRecovery(idempotencyKey, deps, async () =>
+    parseAccepted(await deps.api.revokeSecret(token, options.appKey, {idempotencyKey})));
+  printAccepted("Secret revocation", options.appKey, deps);
+}

package/src/commands/signin.mjs

@@ -1,65 +1,78 @@
 // @ts-check
-
-import { setTimeout as delay } from "node:timers/promises";
+import { createHash, randomBytes } from "node:crypto";
 import { CliError } from "../errors.mjs";
-import { objectString } from "../api-client.mjs";
+import { REQUESTED_OAUTH_SCOPES, validateAuthorizationIssuer } from "../config.mjs";
+import { createLoopbackReceiver } from "../oauth-loopback.mjs";
+import { openBrowser } from "../browser-opener.mjs";
 
-/**
- * @param {{ api: { startSignin(): Promise<{body: unknown}>, pollSignin(deviceCode: string): Promise<{ok: boolean, body: unknown}> }, sessions: { save(session: {accessToken: string, account?: unknown}): Promise<void> }, log: (message: string) => void, wait?: (milliseconds: number) => Promise<unknown> }} deps
+/** @typedef {{
+ * oauth: Pick<import('../oauth-client.mjs').OAuthClient, 'discover' | 'exchangeCode' | 'config'>,
+ * authorizationIssuer?: string,
+ * sessions: {save(credentials: import('../oauth-client.mjs').OAuthCredentials): Promise<void>},
+ * log: (message: string) => void,
+ * openBrowser?: typeof openBrowser,
+ * signal?: AbortSignal,
+ * timeoutMs?: number,
+ * interruptSource?: Pick<NodeJS.Process, 'on' | 'removeListener'>,
+ * }} SigninDependencies
  */
-export async function signin(deps) {
-  const started = await deps.api.startSignin();
-  const deviceCode = required(started.body, "deviceCode");
-  const userCode = required(started.body, "userCode");
-  const verificationUri = required(started.body, "verificationUri");
-  const expiresIn = positiveNumber(started.body, "expiresIn", 600);
-  let interval = positiveNumber(started.body, "interval", 5);
-
-  deps.log(`Open ${verificationUri}`);
-  deps.log(`Enter code: ${userCode}`);
 
-  const deadline = Date.now() + expiresIn * 1000;
-  while (Date.now() < deadline) {
-    await (deps.wait ?? delay)(interval * 1000);
-    const result = await deps.api.pollSignin(deviceCode);
-    const accessToken = objectString(result.body, "accessToken");
-    if (result.ok && accessToken) {
-      const account = result.body && typeof result.body === "object" ? Reflect.get(result.body, "account") : undefined;
-      await deps.sessions.save({ accessToken, account });
-      deps.log("Signed in successfully. The session is stored for the current user.");
-      return;
-    }
-    const code = objectString(result.body, "code");
-    if (code === "authorization_pending") continue;
-    if (code === "slow_down") {
-      interval += 5;
-      continue;
-    }
-    if (code === "access_denied") {
-      throw new CliError("Sign-in was denied", { code, exitCode: 3 });
+/** @param {{noOpen?: boolean}} options @param {SigninDependencies} deps */
+export async function signin({noOpen = false}, deps) {
+  const authorizationIssuer = validateAuthorizationIssuer(deps.authorizationIssuer ?? deps.oauth.config.issuer);
+  const controller = new AbortController();
+  let expired = false;
+  const interruptSource = deps.interruptSource ?? process;
+  const cancel = () => controller.abort();
+  const timer = setTimeout(() => { expired = true; cancel(); }, deps.timeoutMs ?? 600_000);
+  interruptSource.on("SIGINT", cancel);
+  deps.signal?.addEventListener("abort", cancel, {once: true});
+  if (deps.signal?.aborted) cancel();
+  /** @type {Awaited<ReturnType<typeof createLoopbackReceiver>> | undefined} */
+  let receiver;
+  try {
+    const {signal} = controller;
+    const {authorizationEndpoint} = await deps.oauth.discover({signal});
+    signal.throwIfAborted();
+    const state = randomBytes(32).toString("base64url");
+    const verifier = randomBytes(32).toString("base64url");
+    receiver = await createLoopbackReceiver({state, issuer: authorizationIssuer, signal});
+    const authorizeUrl = new URL(authorizationEndpoint);
+    authorizeUrl.search = new URLSearchParams({
+      client_id: deps.oauth.config.clientId,
+      response_type: "code", redirect_uri: receiver.redirectUri,
+      code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+      code_challenge_method: "S256", state, scope: REQUESTED_OAUTH_SCOPES.join(" "),
+    }).toString();
+    if (noOpen) {
+      deps.log(`Open this authorization URL in a browser on this computer:\n${authorizeUrl.href}`);
+    } else {
+      deps.log("Opening your browser to sign in. Complete authorization on this computer.");
+      try { await (deps.openBrowser ?? openBrowser)(authorizeUrl.href, {signal}); }
+      catch {
+        signal.throwIfAborted();
+        deps.log(`Open this authorization URL in a browser on this computer:\n${authorizeUrl.href}`);
+      }
     }
-    if (code === "expired_token") break;
-    throw new CliError(objectString(result.body, "message") ?? "Sign-in failed", {
-      code: code ?? "SIGNIN_FAILED",
-      exitCode: 3,
-    });
+    const {code} = await receiver.result;
+    signal.throwIfAborted();
+    const credentials = await deps.oauth.exchangeCode({code, verifier, redirectUri: receiver.redirectUri, signal});
+    signal.throwIfAborted();
+    await deps.sessions.save(credentials);
+    signal.throwIfAborted();
+    receiver.complete(true);
+    deps.log("Signed in successfully. The session is stored for the current user.");
+  } catch (error) {
+    receiver?.complete(false);
+    if (controller.signal.aborted) throw new CliError(expired
+      ? "Sign-in expired; run `requestshield signin` again"
+      : "Sign-in was cancelled", {code: expired ? "SIGNIN_EXPIRED" : "SIGNIN_CANCELLED", exitCode: 3});
+    if (error instanceof CliError) throw error;
+    throw new CliError("Sign-in failed; run `requestshield signin` again", {code: "SIGNIN_FAILED", exitCode: 3});
+  } finally {
+    clearTimeout(timer);
+    interruptSource.removeListener("SIGINT", cancel);
+    deps.signal?.removeEventListener("abort", cancel);
+    await receiver?.close();
   }
-  throw new CliError("The sign-in code expired; run `requestshield signin` again", {
-    code: "SIGNIN_EXPIRED",
-    exitCode: 3,
-  });
-}
-
-/** @param {unknown} body @param {string} name */
-function required(body, name) {
-  const value = objectString(body, name);
-  if (!value) throw new CliError(`Sign-in response is missing ${name}`);
-  return value;
-}
-
-/** @param {unknown} body @param {string} name @param {number} fallback */
-function positiveNumber(body, name, fallback) {
-  if (!body || typeof body !== "object") return fallback;
-  const value = Reflect.get(body, name);
-  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
 }

package/src/commands/signout.mjs

@@ -0,0 +1,9 @@
+// @ts-check
+
+/** @param {{}} _options
+ * @param {{sessions: {signout(): Promise<{profile: import('../config.mjs').Profile, removed: boolean}>}, log: (message: string) => void}} deps
+ */
+export async function signout(_options, deps) {
+  const { profile, removed } = await deps.sessions.signout();
+  deps.log(removed ? `Signed out locally from ${profile}.` : `No saved local session for ${profile}.`);
+}

package/src/commands/update-check.mjs

@@ -8,9 +8,16 @@ import { CliError } from "../errors.mjs";
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 
 /**
- * @param {{ currentVersion: string, packageName: string, log: (message: string) => void, fetchImpl?: typeof fetch, confirm?: () => Promise<boolean>, install?: (packageName: string, version: string) => Promise<void> }} options
+ * @param {{ currentVersion: string, packageName: string, profile?: "qat" | "stg" | "prod", log: (message: string) => void, fetchImpl?: typeof fetch, confirm?: (latestVersion: string) => Promise<boolean>, install?: (packageName: string, version: string) => Promise<void> }} options
  */
 export async function checkForUpdate(options) {
+  const profile = options.profile ?? "prod";
+  if (profile !== "prod") {
+    options.log(`requestshield-${profile} runs this local repository checkout and has no separately published npm release.`);
+    options.log("Update the checkout with your normal Git workflow.");
+    options.log(`Then run from requestshield-cli/: npx --offline --prefix ./dev requestshield-${profile} <command>`);
+    return;
+  }
   const latestVersion = await fetchLatestVersion(
     options.packageName,
     options.fetchImpl ?? fetch,
@@ -24,15 +31,16 @@ export async function checkForUpdate(options) {
     return;
   }
 
+  options.log(`Update target: global npm installation of ${options.packageName}.`);
   const accepted = await (options.confirm ?? confirmUpdate)(latestVersion);
   if (!accepted) {
     options.log("Update cancelled.");
     return;
   }
 
-  options.log(`Updating RequestShield to ${latestVersion}...`);
+  options.log(`Installing RequestShield ${latestVersion} globally with npm...`);
   await (options.install ?? installWithNpm)(options.packageName, latestVersion);
-  options.log(`RequestShield ${latestVersion} was installed successfully.`);
+  options.log(`RequestShield ${latestVersion} was installed successfully (global npm installation).`);
   options.log("Open a new terminal before running RequestShield again.");
 }
 
@@ -76,7 +84,7 @@ async function confirmUpdate(latestVersion) {
   }
   const prompt = readline.createInterface({ input: stdin, output: stdout });
   try {
-    const answer = await prompt.question(`Update to RequestShield ${latestVersion}? (y/N): `);
+    const answer = await prompt.question(`Install RequestShield ${latestVersion} globally with npm? (y/N): `);
     return answer.trim().toLowerCase() === "y";
   } finally {
     prompt.close();

package/src/config.mjs

@@ -1,8 +1,150 @@
-export const DEFAULT_MANAGEMENT_API_URL =
-    "https://api.intellifend.ai";
+// @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";
+
+/** @typedef {'qat' | 'stg' | 'prod'} Profile */
+const PROFILES = new Set(["qat", "stg", "prod"]);
+const CONFIG_KEYS = new Set(["API_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";
+    "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(`OAuth is not configured for ${getCommandName(profile)}. Set OAUTH_ISSUER and OAUTH_CLIENT_ID in config/.env.${profile}.`);
+  }
+  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("OAUTH_AUTHORIZATION_ISSUER must be a nonempty identifier of at most 2048 printable ASCII characters without spaces");
+  }
+  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("OAUTH_ISSUER must use HTTPS");
+  if (typeof clientId !== "string" || !/^[A-Za-z0-9._~-]{1,256}$/.test(clientId)) {
+    throw invalidConfig("Set OAUTH_CLIENT_ID to the public Connected App client ID");
+  }
+  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);
+}
+
+/** @param {Record<string, string | undefined>} values @param {Profile} profile */
+function configuredApiUrl(values, profile) {
+  if (!values.API_URL) {
+    throw invalidConfig(`The Management API is not configured for ${getCommandName(profile)}. Set API_URL in config/.env.${profile}.`);
+  }
+  return validatedUrl(values.API_URL, "API_URL");
+}
+
+/** @param {Profile} [profile] */
+export function getCommandName(profile = "prod") {
+  validateProfile(profile);
+  return profile === "prod" ? "requestshield" : `requestshield-${profile}`;
+}
+
+/** Keep suggested commands runnable from either supported source directory.
+ * @param {Profile} [profile] @param {string} [cwd]
+ */
+export function getCommandInvocation(profile = "prod", cwd = process.cwd()) {
+  const command = getCommandName(profile);
+  if (profile === "prod") 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("Unknown RequestShield environment profile");
+}
+
+/** @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(`Cannot read config/.env.${profile} for ${getCommandName(profile)}. Restore the package configuration file.`);
+  }
+  if (Object.keys(values).some(key => !CONFIG_KEYS.has(key))) {
+    throw invalidConfig(`config/.env.${profile} accepts only API_URL, OAUTH_ISSUER, OAUTH_CLIENT_ID and OAUTH_AUTHORIZATION_ISSUER; do not store credentials in this file.`);
+  }
+  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 signin` 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(`${name} must be a valid HTTPS URL (HTTP is allowed only on loopback)`);
+  }
+}
+
+/** @param {string} message */
+function invalidConfig(message) {
+  return new CliError(message, { code: "OAUTH_CONFIG_INVALID", exitCode: 2 });
+}

package/src/entrypoint.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+import { run } from "./cli.mjs";
+import { CliError } from "./errors.mjs";
+import { getCommandInvocation, getCommandName } from "./config.mjs";
+
+/** @param {import('./config.mjs').Profile} profile */
+export async function main(profile) {
+  const command = getCommandName(profile);
+  const invocation = getCommandInvocation(profile);
+  try {
+    await run(process.argv.slice(2), {profile});
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Rewrite only fixed CLI guidance on stderr. Successful JSON and app names
+    // pass through untouched, including names containing "requestshield".
+    const guidance = message
+      .replaceAll("`requestshield signin`", `\`${invocation} signin\``)
+      .replaceAll("`requestshield signout`", `\`${invocation} signout\``)
+      .replaceAll("Usage: requestshield ", `Usage: ${invocation} `)
+      .replace(/^  requestshield /gm, `  ${invocation} `);
+    console.error(`${command}: ${guidance}`);
+    process.exitCode = error instanceof CliError ? error.exitCode : 1;
+  }
+}

package/src/errors.mjs

@@ -3,12 +3,14 @@
 export class CliError extends Error {
   /**
    * @param {string} message
-   * @param {{ code?: string, exitCode?: number }} [options]
+   * @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/main.mjs

@@ -1,25 +1,6 @@
 #!/usr/bin/env node
 // @ts-check
 
-import { run } from "./cli.mjs";
-import { CliError } from "./errors.mjs";
+import { main } from "./entrypoint.mjs";
 
-async function main() {
-    try {
-        await run(process.argv.slice(2));
-    } catch (error) {
-        const message =
-            error instanceof Error
-                ? error.message
-                : String(error);
-
-        console.error(`requestshield: ${message}`);
-
-        process.exitCode =
-            error instanceof CliError
-                ? error.exitCode
-                : 1;
-    }
-}
-
-void main();
+void main("prod");