requestshield 0.0.0-stage → 1.0.0-stg.276

package/src/commands/contract.mjs

@@ -0,0 +1,59 @@
+// @ts-check
+import { getDocsUrl } from "../config.mjs";
+import { IntegrationContractClient } from "../integration-contract-client.mjs";
+import { rendererFor } from "../terminal.mjs";
+
+/**
+ * @param {{json?: boolean}} options
+ * @param {{profile?: import('../config.mjs').Profile, fetchImpl?: typeof fetch, log(message: string): void, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function showContract(options, deps) {
+  const profile = deps.profile ?? "prod";
+  const contract = await new IntegrationContractClient({
+    docsUrl: getDocsUrl(profile), fetchImpl: deps.fetchImpl,
+  }).getContract();
+  if (options.json) deps.log(JSON.stringify(contract, null, 2));
+  else {
+    const {data} = contract;
+    const renderer = rendererFor(deps);
+    /** @type {Array<[string, string]>} */
+    const documentationFields = [
+      ["Browser SDK", data.documentation.browserSdk],
+      ["Java SDK", data.documentation.javaSdk],
+      ["Domains and CSP", data.documentation.domainsAndCsp],
+    ];
+    if (data.documentation.releaseNotes) documentationFields.push(["Release notes", data.documentation.releaseNotes]);
+    deps.log([
+      renderer.heading("Integration contract", "📖"),
+      renderer.fields([
+        ["Version", `${data.contractVersion} (schema ${data.schemaVersion})`],
+        ["Challenge service", data.services.challengeUrl],
+      ]),
+      renderer.section("Browser SDK"),
+      renderer.fields([
+        ["Versioned script version", data.browser.sdkVersion],
+        ["Versioned script", data.browser.scriptUrlVersion],
+        ["Latest script", data.browser.scriptUrlLatest],
+        ["Versioned script integrity", data.browser.integrity],
+        ["Token header", data.browser.tokenHeader],
+        ["Versioned script modes", data.browser.availableModes.join(", ")],
+      ]),
+      renderer.section("CSP additions"),
+      renderer.fields([
+        ["script-src", data.browser.cspAdditions.scriptSrc.join(" ")],
+        ["connect-src", data.browser.cspAdditions.connectSrc.join(" ")],
+        ["worker-src", data.browser.cspAdditions.workerSrc.join(" ")],
+      ]),
+      renderer.section("Java SDK"),
+      renderer.fields([
+        ["Version", `${data.backend.sdkVersion} (JDK ${data.backend.minJdk}+)`],
+        ["Maven repository", data.backend.mavenRepository],
+        ["Manual — Java core", `${data.backend.core.groupId}:${data.backend.core.artifactId}:${data.backend.sdkVersion}`],
+        [`Seamless — ${data.backend.springBoot3.framework} starter`, `${data.backend.springBoot3.groupId}:${data.backend.springBoot3.artifactId}:${data.backend.sdkVersion}`],
+      ]),
+      renderer.section("Documentation"),
+      renderer.fields(documentationFields),
+    ].join("\n\n"));
+  }
+  return contract;
+}

package/src/commands/keys-create.mjs

@@ -0,0 +1,22 @@
+// @ts-check
+
+import { mutationKey, parseIssuance, printIssuance, withMutationRecovery } from "./mutation-support.mjs";
+import { outputContext } from "./output.mjs";
+import { saveSecretOutput, withSecretOutput } from "./secret-output.mjs";
+
+/**
+ * @param {{appName: string, json?: boolean, yes?: boolean, idempotencyKey?: string, output?: string}} options
+ * @param {import('./mutation-support.mjs').CommandOutput & {api: {createApp(token: string, options: {name: string, idempotencyKey: string}): Promise<import('./mutation-support.mjs').MutationResponse>}, sessions: {loadToken(): Promise<string>}}} deps
+ */
+export async function createKeys(options, deps) {
+  deps = outputContext(options, deps);
+  const idempotencyKey = mutationKey(options.idempotencyKey);
+  return withSecretOutput(options.output, deps, async (file) => {
+    const token = await deps.sessions.loadToken();
+    const issuance = await withMutationRecovery(idempotencyKey, deps, async () =>
+      parseIssuance(await deps.api.createApp(token, {name: options.appName, idempotencyKey}), 201));
+    if (file) return saveSecretOutput(file, issuance, options, deps);
+    printIssuance(issuance, deps, options);
+    return issuance;
+  });
+}

package/src/commands/mutation-support.mjs

@@ -0,0 +1,135 @@
+// @ts-check
+import { randomUUID } from "node:crypto";
+import readline from "node:readline/promises";
+import { stdin, stderr } from "node:process";
+import { printData } from "./output.mjs";
+import { CliError } from "../errors.mjs";
+import { getCommandInvocation } from "../config.mjs";
+import { APPLICATION_STATUSES, invalidResponse, responseObject } from "./application-response.mjs";
+import { rendererFor } from "../terminal.mjs";
+
+/** @typedef {{body: unknown, status?: number, replayed?: boolean}} MutationResponse */
+/** @typedef {{log: (message: string) => void, warn?: (message: string) => void, profile?: import('../config.mjs').Profile, terminal?: import('../terminal.mjs').TerminalContext, confirm?: () => Promise<boolean>, secretOutput?: import('../secret-output.mjs').SecretOutputOptions}} 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, json?: boolean}} options @param {CommandOutput} deps @param {string} prompt @param {string} word */
+export async function confirmAction(options, deps, prompt, word) {
+  if (options.yes) return;
+  if (options.json) throw new CliError("This action requires confirmation; use --yes with --json", {code: "CONFIRMATION_REQUIRED", exitCode: 2});
+  let accepted;
+  if (deps.confirm) accepted = await deps.confirm();
+  else {
+    if (!stdin.isTTY || !stderr.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: stderr});
+    try { accepted = await terminal.question(`${rendererFor(deps, "stderr").message("warning", prompt)}\nType ${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 @param {{json?: boolean}} [options] */
+export function printIssuance(issuance, deps, options = {}) {
+  const invocation = getCommandInvocation(deps.profile);
+  if (options.json) {
+    printData(issuance, deps);
+    const warn = deps.warn ?? console.error;
+    if (issuance.apiSecret === null) warn(`This is an idempotency replay; the API did not return a secret. Run \`${invocation} secret reveal ${issuance.appKey}\` to retrieve the current active secret.`);
+    else warn("Store this secret in your backend secret manager. The CLI did not save it.");
+    (deps.warn ?? console.error)("Changes may take a moment. Check the application status before relying on the change.");
+    return;
+  }
+  const renderer = rendererFor(deps);
+  const diagnostics = rendererFor(deps, deps.warn ? "stderr" : "stdout");
+  const warn = deps.warn ?? deps.log;
+  deps.log(renderer.heading("Application credentials", "🔐"));
+  deps.log(renderer.fields([["App Key", issuance.appKey], ["Status", issuance.status]]));
+  if (issuance.apiSecret === null) {
+    warn(diagnostics.message("warning", `This is an idempotency replay; the API did not return a secret. Run \`${invocation} secret reveal ${issuance.appKey}\` to retrieve the current active secret.`));
+  } else {
+    deps.log(renderer.fields([["Secret Key", issuance.apiSecret]]));
+    warn(diagnostics.message("warning", "Store this secret in your backend secret manager. The CLI did not save it."));
+  }
+  warn(diagnostics.message("warning", "Changes may take a moment. Check the application status before relying on the change."));
+}
+
+/** @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 @param {{json?: boolean}} [options] */
+export function printAccepted(action, appKey, deps, options = {}) {
+  const data = {appKey, status: "accepted"};
+  if (options.json) printData(data, deps);
+  else {
+    const renderer = rendererFor(deps);
+    deps.log(renderer.heading(`${action} accepted`));
+    deps.log(renderer.fields([["App Key", appKey], ["Status", "accepted"]]));
+  }
+  const diagnostics = rendererFor(deps, deps.warn ? "stderr" : "stdout");
+  const warning = "Changes may take a moment.";
+  const guidance = `Run \`${getCommandInvocation(deps.profile)} app get ${appKey}\` to check the current application status.`;
+  (deps.warn ?? deps.log)(options.json ? warning : diagnostics.message("warning", warning));
+  (deps.warn ?? deps.log)(options.json ? guidance : diagnostics.paragraph(guidance));
+  return data;
+}

package/src/commands/output.mjs

@@ -0,0 +1,26 @@
+// @ts-check
+import { rendererFor } from "../terminal.mjs";
+
+/** @param {unknown} data @param {{log(message: string): void}} deps */
+export function printData(data, deps) {
+  deps.log(JSON.stringify({data}, null, 2));
+}
+
+/** Keep diagnostics separate from machine-readable results, including direct callers.
+ * @template {{log: (message: string) => void, warn?: (message: string) => void}} T
+ * @param {{json?: boolean}} options @param {T} deps @returns {T}
+ */
+export function outputContext(options, deps) {
+  return {...deps, warn: deps.warn ?? (options.json ? console.error : deps.log)};
+}
+
+/** @param {import('./application-response.mjs').Application} app
+ * @param {{json?: boolean}} options @param {{log(message: string): void, terminal?: import('../terminal.mjs').TerminalContext}} deps */
+export function printApplication(app, options, deps) {
+  if (options.json) return printData(app, deps);
+  const renderer = rendererFor(deps);
+  deps.log([renderer.heading("Application", "📦"), "", renderer.fields([
+    ["App Key", app.appKey], ["Name", app.name], ["Status", app.status],
+    ["Created", app.createdAt], ["Updated", app.updatedAt],
+  ])].join("\n"));
+}

package/src/commands/secret-commands.mjs

@@ -0,0 +1,66 @@
+// @ts-check
+import { invalidResponse, responseObject } from "./application-response.mjs";
+import { outputContext, printData } from "./output.mjs";
+import { rendererFor } from "../terminal.mjs";
+import { confirmAction, isApiSecret, mutationKey, parseAccepted, parseIssuance, printAccepted, printIssuance, validateHttpStatus, withMutationRecovery } from "./mutation-support.mjs";
+import { saveSecretOutput, withSecretOutput } from "./secret-output.mjs";
+
+/** @typedef {import('./mutation-support.mjs').MutationResponse} MutationResponse */
+/** @typedef {import('./mutation-support.mjs').CommandOutput & {sessions: {loadToken(): Promise<string>}}} Dependencies */
+/** @typedef {{appKey: string, yes?: boolean, json?: boolean, idempotencyKey?: string}} MutationOptions */
+
+/** @param {MutationOptions & {output?: string}} options
+ * @param {Dependencies & {api: {rotateSecret(token: string, appKey: string, options: {idempotencyKey: string}): Promise<MutationResponse>}}} deps
+ */
+export async function rotateSecret(options, deps) {
+  deps = outputContext(options, deps);
+  await confirmAction(options, deps, `Replace the current secret for ${options.appKey}?${options.output === undefined ? "" : " Save the new credentials to the selected output file?"} Existing backend configuration will need the new secret.`, "ROTATE");
+  const idempotencyKey = mutationKey(options.idempotencyKey);
+  return withSecretOutput(options.output, deps, async (file) => {
+    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));
+    if (file) return saveSecretOutput(file, issuance, options, deps);
+    printIssuance(issuance, deps, options);
+    return issuance;
+  });
+}
+
+/** @param {{appKey: string, yes?: boolean, json?: boolean, output?: string}} options
+ * @param {Dependencies & {api: {revealSecret(token: string, appKey: string): Promise<MutationResponse>}}} deps
+ */
+export async function revealSecret(options, deps) {
+  deps = outputContext(options, deps);
+  await confirmAction(options, deps, options.output === undefined
+    ? `Display the current API secret for ${options.appKey} in this terminal?`
+    : `Retrieve the current API secret for ${options.appKey} and save the credentials to the selected output file?`, "REVEAL");
+  return withSecretOutput(options.output, deps, async (file) => {
+    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");
+    if (file) return saveSecretOutput(file, {appKey: options.appKey, apiSecret}, options, deps);
+    if (options.json) printData({apiSecret}, deps);
+    else {
+      const renderer = rendererFor(deps);
+      deps.log(`${renderer.heading("Application secret", "🔐")}\n\n${renderer.fields([["Secret Key", apiSecret]])}`);
+    }
+    const notice = "Store this secret in your backend secret manager. The CLI did not save it.";
+    (deps.warn ?? deps.log)(options.json ? notice : rendererFor(deps, deps.warn ? "stderr" : "stdout").message("warning", notice));
+    return {apiSecret};
+  });
+}
+
+/** @param {MutationOptions} options
+ * @param {Dependencies & {api: {revokeSecret(token: string, appKey: string, options: {idempotencyKey: string}): Promise<MutationResponse>}}} deps
+ */
+export async function revokeSecret(options, deps) {
+  deps = outputContext(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})));
+  return printAccepted("Secret revocation", options.appKey, deps, options);
+}

package/src/commands/secret-output.mjs

@@ -0,0 +1,52 @@
+// @ts-check
+import { SecretOutputFile } from "../secret-output.mjs";
+import { CliError } from "../errors.mjs";
+import { getCommandInvocation } from "../config.mjs";
+import { rendererFor } from "../terminal.mjs";
+import { printData } from "./output.mjs";
+
+/** Reserve storage before session loading/API calls and clean up on every failure.
+ * @template T @param {string | undefined} output
+ * @param {import('./mutation-support.mjs').CommandOutput} deps
+ * @param {(file?: SecretOutputFile) => Promise<T>} operation
+ */
+export async function withSecretOutput(output, deps, operation) {
+  if (output === undefined) return operation();
+  const file = new SecretOutputFile(output, deps.secretOutput);
+  try {
+    await file.prepare();
+    return await operation(file);
+  } finally {
+    if (!await file.cleanup()) (deps.warn ?? deps.log)("Could not remove the unfinished output file. Inspect the selected path privately before using it again.");
+  }
+}
+
+/** @param {SecretOutputFile} file
+ * @param {{appKey: string, apiSecret: string | null, status?: string}} credentials
+ * @param {{json?: boolean}} options
+ * @param {import('./mutation-support.mjs').CommandOutput} deps
+ */
+export async function saveSecretOutput(file, credentials, options, deps) {
+  const {appKey, apiSecret, status} = credentials;
+  const recover = `Run \`${getCommandInvocation(deps.profile)} secret reveal ${appKey} --output <new-file>\` to save the current active secret. Do not create or rotate again.`;
+  if (apiSecret === null) {
+    throw new CliError(`Application ${appKey}: this idempotency replay returned no secret, so no credentials file was saved. ${recover}`, {code: "OUTPUT_SECRET_UNAVAILABLE", exitCode: 7});
+  }
+  try { await file.commit(appKey, apiSecret); }
+  catch {
+    throw new CliError(`The application or secret request for ${appKey} succeeded, but the credentials file could not be saved. ${recover}`, {code: "OUTPUT_WRITE_FAILED", exitCode: 7});
+  }
+  const data = {appKey, ...(status === undefined ? {} : {status}), outputPath: file.file, secretStored: true};
+  if (options.json) printData(data, deps);
+  else {
+    const renderer = rendererFor(deps);
+    /** @type {Array<[string, string]>} */
+    const fields = [["App Key", appKey]];
+    if (status !== undefined) fields.push(["Status", status]);
+    fields.push(["Output file", file.file], ["Secret stored", "yes"]);
+    deps.log([renderer.heading("Credentials saved", "🔐"), "", renderer.fields(fields)].join("\n"));
+  }
+  (deps.warn ?? deps.log)("Configure your backend launcher or container to load this ENV file. Saving it does not configure the backend.");
+  if (status !== undefined) (deps.warn ?? deps.log)("Changes may take a moment. Check the application status before relying on the change.");
+  return data;
+}

package/src/commands/service-status.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+import { getServiceConfig } from '../config.mjs';
+import { checkServices } from '../service-status-client.mjs';
+import { CommandCompletion } from '../command-completion.mjs';
+import { rendererFor } from '../terminal.mjs';
+
+/** @param {{json?: boolean}} options
+ * @param {{profile?: import('../config.mjs').Profile, fetchImpl?: typeof fetch, log(message: string): void, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function showServiceStatus(options, deps) {
+  const profile = deps.profile ?? 'prod';
+  const config = getServiceConfig(profile);
+  const checkedAt = new Date().toISOString();
+  const checks = await checkServices({...config, fetchImpl: deps.fetchImpl});
+  const result = {data: {checkedAt, checks}};
+  if (options.json) deps.log(JSON.stringify(result, null, 2));
+  else {
+    const renderer = rendererFor(deps);
+    deps.log([
+      renderer.heading('Service status'),
+      renderer.fields([['Checked at', checkedAt]]),
+      ...checks.map(check => [
+        renderer.section(check.service === 'management-api' ? 'Management API' : 'Challenge Service'),
+        renderer.fields([
+          ['URL', check.url], ['Status', check.status], ['Response time', `${check.latencyMs} ms`],
+          ['HTTP status', check.httpStatus === null ? 'Unavailable' : String(check.httpStatus)],
+          ['Reason', check.reason ?? 'None'],
+        ]),
+      ].join('\n')),
+      renderer.paragraph('Results reflect checks from this computer at the time shown. Test a protected request to verify your application integration.'),
+    ].join('\n\n'));
+  }
+  return new CommandCompletion(checks.every(check => check.status === 'ok') ? 0 : 1);
+}

package/src/commands/signin.mjs

@@ -0,0 +1,95 @@
+// @ts-check
+import { createHash, randomBytes } from "node:crypto";
+import { CliError } from "../errors.mjs";
+import { REQUESTED_OAUTH_SCOPES, validateAuthorizationIssuer } from "../config.mjs";
+import { createLoopbackReceiver } from "../oauth-loopback.mjs";
+import { openBrowser } from "../browser-opener.mjs";
+import { printData, outputContext } from "./output.mjs";
+import { rendererFor } from "../terminal.mjs";
+
+/** @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,
+ * warn?: (message: string) => void,
+ * profile?: import('../config.mjs').Profile,
+ * openBrowser?: typeof openBrowser,
+ * signal?: AbortSignal,
+ * timeoutMs?: number,
+ * interruptSource?: Pick<NodeJS.Process, 'on' | 'removeListener'>,
+ * terminal?: import('../terminal.mjs').TerminalContext,
+ * }} SigninDependencies
+ */
+
+/** @param {{noOpen?: boolean, json?: boolean}} options @param {SigninDependencies} deps */
+export async function signin(options, deps) {
+  const {noOpen = false} = options;
+  deps = outputContext(options, deps);
+  const progress = deps.warn ?? deps.log;
+  const diagnostics = rendererFor(deps, "stderr");
+  /** @param {string} text */
+  const progressMessage = text => options.json ? text : diagnostics.message("info", text);
+  /** Preserve the full authorization URL on its own line, including in JSON diagnostics.
+   * @param {string} url */
+  const showAuthorizationUrl = url => progress(`${progressMessage("Open this authorization URL in a browser on this computer:")}\n${url}`);
+  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) {
+      showAuthorizationUrl(authorizeUrl.href);
+    } else {
+      progress(progressMessage("Opening your browser to sign in. Complete authorization on this computer."));
+      try { await (deps.openBrowser ?? openBrowser)(authorizeUrl.href, {signal}); }
+      catch {
+        signal.throwIfAborted();
+        showAuthorizationUrl(authorizeUrl.href);
+      }
+    }
+    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);
+    const result = {signedIn: true};
+    if (options.json) printData(result, deps);
+    else deps.log(rendererFor(deps).message("success", "Signed in successfully. The session is stored for the current user."));
+    return result;
+  } catch (error) {
+    receiver?.complete(false);
+    if (controller.signal.aborted) throw new CliError(expired
+      ? "Sign-in expired; run `requestshield login` 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 login` again", {code: "SIGNIN_FAILED", exitCode: 3});
+  } finally {
+    clearTimeout(timer);
+    interruptSource.removeListener("SIGINT", cancel);
+    deps.signal?.removeEventListener("abort", cancel);
+    await receiver?.close();
+  }
+}

package/src/commands/signout.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+
+import { printData } from "./output.mjs";
+import { rendererFor } from "../terminal.mjs";
+
+/** @param {{json?: boolean}} options
+ * @param {{sessions: {signout(): Promise<{profile: import('../config.mjs').Profile, removed: boolean}>}, log: (message: string) => void, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function signout(options, deps) {
+  const { removed } = await deps.sessions.signout();
+  if (options.json) printData({removed}, deps);
+  else deps.log(rendererFor(deps).message(removed ? "success" : "info", removed ? "Signed out." : "No saved session."));
+  return {removed};
+}