requestshield 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# RequestShield CLI
+
+Customer-facing CLI for signing in, rotating RequestShield application keys,
+and installing the RequestShield skill for Codex.
+
+## Requirements
+
+- Node.js 22.13 or newer.
+- A customer management API implementing the contract below.
+
+The API defaults to `https://api.intellifend.ai`. For development, set
+`REQUESTSHIELD_API_URL` to the management API origin.
+
+## Commands
+
+```console
+requestshield signin
+requestshield keys create
+requestshield agent setup --agent codex
+```
+
+`signin` starts a device authorization flow and prints the verification URL and
+code for the customer to open manually. The returned session is stored under the user's standard
+application-data directory with permissions restricted to that user. CI may
+instead provide `REQUESTSHIELD_ACCESS_TOKEN`; environment tokens are never
+persisted.
+
+`keys create` asks for confirmation, then atomically deactivates the previous
+application credentials and creates a new `appKey` + `apiSecret`. The public
+app key and the backend-only secret are printed after success. The secret is
+not stored by the CLI and cannot be retrieved again.
+
+`agent setup --agent codex` installs the bundled `requestshield` skill into
+`$CODEX_HOME/skills`, or `~/.codex/skills` when `CODEX_HOME` is unset. Existing
+content is preserved unless `--force` is supplied.
+
+## Management API contract
+
+### Start sign-in
+
+`POST /v1/cli/signin`
+
+```json
+{
+  "client": "requestshield-cli"
+}
+```
+
+The response contains `deviceCode`, `userCode`, `verificationUri`,
+`expiresIn`, and `interval`.
+
+### Poll sign-in
+
+`POST /v1/cli/signin/token` with `{ "deviceCode": "..." }`.
+
+Pending responses use HTTP 400 with `code` set to `authorization_pending` or
+`slow_down`. A successful response contains `accessToken` and optional account
+metadata.
+
+### Rotate keys
+
+`POST /v1/cli/keys/rotate` with Bearer authentication and an empty JSON body.
+The response contains `appKey` and one-time `apiSecret`.
+
+## Development
+
+```console
+pnpm --filter requestshield lint
+pnpm --filter requestshield typecheck
+pnpm --filter requestshield test
+pnpm --filter requestshield build
+```
+## Quick start
+
+RequestShield requires Node.js 22.13 or newer.
+
+Run without installing globally:
+
+```console
+npx requestshield --help
+npx requestshield signin
+npx requestshield keys create
+npx requestshield agent setup --agent codex
+```
+
+Pin a specific version for reproducible usage:
+
+```console
+npx requestshield@0.1.0 --help
+```
+
+To automatically accept npm's installation prompt:
+
+```console
+npx --yes requestshield@0.1.0 --help
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "requestshield",
+  "version": "0.1.0",
+  "description": "Customer CLI for IntelliFend RequestShield.",
+  "type": "module",
+  "bin": {
+    "requestshield": "src/main.mjs"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "scripts": {
+    "build": "node scripts/check-package.mjs",
+    "lint": "node scripts/check-package.mjs",
+    "test": "node --test",
+    "typecheck": "tsc -p jsconfig.json --noEmit",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "esbuild": "^0.28.1",
+    "postject": "1.0.0-alpha.6",
+    "typescript": "^6.0.3"
+  },
+  "license": "UNLICENSED"
+}

package/skills/requestshield/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: requestshield
+description: Set up or remove IntelliFend RequestShield protection in a customer application using the repository's Browser SDK and supported backend SDK. Use when the user asks an AI agent to integrate, configure, validate, or remove RequestShield protection.
+---
+
+# RequestShield Integration
+
+Work only inside the customer's application repository. Do not access or modify
+IntelliFend operator infrastructure, Cloudflare resources, or customer records.
+
+Before editing, identify the frontend and backend frameworks and inspect the
+relevant dependency and configuration files. Explain the files that will change.
+Do not place the backend Secret Key in source, browser configuration, URLs, logs,
+or committed files. The public App Key may be included in browser configuration.
+
+## Set up protection
+
+1. Obtain the public App Key, backend-only Secret Key, and Challenge Server URL
+   from the customer. If the Secret Key is unavailable, stop and ask the user to
+   put it in their backend secret manager; never ask them to paste it into chat.
+2. Configure the Browser SDK with the App Key, Challenge Server URL, and exact
+   protected endpoint URLs. Query strings and fragments do not participate in
+   matching; path case and trailing slash do.
+3. Configure the supported backend SDK with the same App Key and a secret-store
+   reference for the Secret Key. For Spring Boot 3 MVC, protect the actual
+   mutation method with `@RequestShieldProtected`.
+4. For a new endpoint, start in `MONITOR`; move to `BLOCK` only after verifying
+   browser matching, backend outcomes, and CORS. Cross-origin customer APIs must
+   allow `X-IntelliFend-Token`.
+5. Run the project's normal lint, build, and tests. Report any manual secret or
+   deployment step without performing external deployment unless requested.
+
+Do not combine a manual `RequestShieldClient.verify(token)` call with annotation
+enforcement on the same request: the token is single-use and would be consumed
+twice.
+
+## Remove protection
+
+Remove only RequestShield-owned integration: browser initialization/protected
+URL entries, backend annotation/configuration, and dependencies that have no
+remaining callers. Preserve unrelated CORS, environment, build, and application
+configuration. Never delete or rotate remote keys as part of source removal.
+Run the project's normal validation after the change.
+

package/src/api-client.mjs

@@ -0,0 +1,106 @@
+// @ts-check
+
+import { CliError } from "./errors.mjs";
+
+export class ManagementApiClient {
+  /** @param {{ baseUrl: string, fetchImpl?: typeof fetch }} options */
+  constructor({ baseUrl, fetchImpl = fetch }) {
+    let url;
+    try {
+      url = new URL(baseUrl);
+    } catch {
+      throw new CliError("REQUESTSHIELD_API_URL must be a valid URL", { exitCode: 2 });
+    }
+    if (url.protocol !== "https:" && !isLoopback(url)) {
+      throw new CliError("The management API must use HTTPS except on loopback", {
+        exitCode: 2,
+      });
+    }
+    this.baseUrl = url.href.replace(/\/$/, "");
+    this.fetchImpl = fetchImpl;
+  }
+
+  async startSignin() {
+    return this.#request("/v1/cli/signin", {
+      method: "POST",
+      body: JSON.stringify({ client: "requestshield-cli" }),
+    });
+  }
+
+  /** @param {string} deviceCode */
+  async pollSignin(deviceCode) {
+    return this.#request(
+      "/v1/cli/signin/token",
+      { method: "POST", body: JSON.stringify({ deviceCode }) },
+      true,
+    );
+  }
+
+  /** @param {string} accessToken */
+  async rotateKeys(accessToken) {
+    return this.#request("/v1/cli/keys/rotate", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: "{}",
+    });
+  }
+
+  /**
+   * @param {string} path
+   * @param {RequestInit} init
+   * @param {boolean} [allowErrorBody]
+   */
+  async #request(path, init, allowErrorBody = false) {
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        ...init,
+        headers: { "Content-Type": "application/json", ...init.headers },
+        signal: AbortSignal.timeout(15_000),
+      });
+    } catch (error) {
+      throw new CliError(`Could not reach the RequestShield API: ${messageOf(error)}`, {
+        code: "NETWORK_ERROR",
+        exitCode: 7,
+      });
+    }
+
+    const text = await response.text();
+    let body = {};
+    if (text !== "") {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        throw new CliError("The RequestShield API returned invalid JSON", {
+          code: "INVALID_RESPONSE",
+        });
+      }
+    }
+    if (!response.ok && !allowErrorBody) {
+      const detail = objectString(body, "message") ?? `HTTP ${response.status}`;
+      const exitCode = response.status === 401 || response.status === 403 ? 3 : 1;
+      throw new CliError(`RequestShield API error: ${detail}`, {
+        code: objectString(body, "code") ?? "API_ERROR",
+        exitCode,
+      });
+    }
+    return { ok: response.ok, status: response.status, body };
+  }
+}
+
+/** @param {URL} url */
+function isLoopback(url) {
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+}
+
+/** @param {unknown} value @param {string} property */
+export function objectString(value, property) {
+  if (!value || typeof value !== "object") return undefined;
+  const found = Reflect.get(value, property);
+  return typeof found === "string" ? found : undefined;
+}
+
+/** @param {unknown} error */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/args.mjs

@@ -0,0 +1,75 @@
+// @ts-check
+
+import { CliError } from "./errors.mjs";
+
+const HELP = `RequestShield customer CLI
+
+Usage:
+  requestshield signin
+  requestshield keys create [--yes]
+  requestshield agent setup --agent codex [--force]
+  requestshield --help
+  requestshield --version`;
+
+/**
+ * @typedef {{ command: "help", help: string }
+ * | { command: "version" }
+ * | { command: "signin" }
+ * | { command: "keys-create", yes: boolean }
+ * | { command: "agent-setup", agent: "codex", force: boolean }} ParsedArgs
+ */
+
+/** @param {string[]} argv @returns {ParsedArgs} */
+export function parseArgs(argv) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    return { command: "help", help: HELP };
+  }
+  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-V")) {
+    return { command: "version" };
+  }
+  if (argv[0] === "signin") {
+    assertOnly(argv.slice(1), new Set());
+    return { command: "signin" };
+  }
+  if (argv[0] === "keys" && argv[1] === "create") {
+    assertOnly(argv.slice(2), new Set(["--yes"]));
+    return { command: "keys-create", yes: argv.includes("--yes") };
+  }
+  if (argv[0] === "agent" && argv[1] === "setup") {
+    const rest = argv.slice(2);
+    /** @type {string | undefined} */
+    let agent;
+    let force = false;
+    for (let index = 0; index < rest.length; index++) {
+      const arg = rest[index];
+      if (arg === "--force") {
+        force = true;
+      } else if (arg === "--agent") {
+        agent = rest[++index];
+        if (!agent || agent.startsWith("--")) {
+          throw new CliError("--agent needs a value", { exitCode: 2 });
+        }
+      } else {
+        throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
+      }
+    }
+    if (agent !== "codex") {
+      throw new CliError("--agent codex is required; no other agent is supported", {
+        exitCode: 2,
+      });
+    }
+    return { command: "agent-setup", agent: "codex", force };
+  }
+  throw new CliError(`Unknown command.\n\n${HELP}`, { exitCode: 2 });
+}
+
+/** @param {string[]} args @param {Set<string>} allowed */
+function assertOnly(args, allowed) {
+  for (const arg of args) {
+    if (!allowed.has(arg)) {
+      throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
+    }
+  }
+}
+
+export { HELP };

package/src/cli.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { parseArgs } from "./args.mjs";
+import { ManagementApiClient } from "./api-client.mjs";
+import { SessionStore } from "./session-store.mjs";
+import { signin } from "./commands/signin.mjs";
+import { createKeys } from "./commands/keys-create.mjs";
+import { setupAgent } from "./commands/agent-setup.mjs";
+import packageJson from "../package.json" with { type: "json" };
+
+/**
+ * @param {string[]} argv
+ * @param {{ log?: (message: string) => void, api?: ManagementApiClient, sessions?: SessionStore, env?: NodeJS.ProcessEnv, homeDir?: string, sourceDir?: string, wait?: (milliseconds: number) => Promise<unknown>, confirm?: () => Promise<boolean> }} [deps]
+ */
+export async function run(argv, deps = {}) {
+  const parsed = parseArgs(argv);
+  const log = deps.log ?? ((message) => console.log(message));
+  if (parsed.command === "help") return log(parsed.help);
+  if (parsed.command === "version") return log(packageJson.version);
+
+  if (parsed.command === "agent-setup") {
+    return setupAgent(parsed, { log, ...deps });
+  }
+
+  const env = deps.env ?? process.env;
+
+  const api = deps.api ?? new ManagementApiClient({
+    baseUrl:
+        env.REQUESTSHIELD_API_URL ??
+        "https://api.intellifend.ai",
+  });
+
+  const sessions = deps.sessions ?? new SessionStore({
+    env,
+    homeDir: deps.homeDir,
+  });
+  if (parsed.command === "signin") return signin({ api, sessions, log, ...deps });
+  if (parsed.command === "keys-create") return createKeys(parsed, { api, sessions, log, ...deps });
+}

package/src/commands/agent-setup.mjs

@@ -0,0 +1,91 @@
+// @ts-check
+
+import { cp, lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { CliError } from "../errors.mjs";
+import { getAsset, isSea } from "node:sea";
+
+const skillAsset = "requestshield-skill.md";
+
+/**
+ * @param {{ agent: string, force: boolean }} options
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string }} deps
+ */
+export async function setupAgent(options, deps) {
+  if (options.agent !== "codex") {
+    throw new CliError(`Unsupported agent: ${options.agent}`, { exitCode: 2 });
+  }
+  const env = deps.env ?? process.env;
+  const codexHome = env.CODEX_HOME || path.join(deps.homeDir ?? os.homedir(), ".codex");
+  const skillsRoot = path.join(codexHome, "skills");
+  const destination = path.join(skillsRoot, "requestshield");
+  await mkdir(skillsRoot, { recursive: true });
+
+  const exists = await pathExists(destination);
+  if (exists && !options.force) {
+    throw new CliError(`RequestShield skill already exists at ${destination}; use --force to replace it`, {
+      code: "SKILL_EXISTS",
+      exitCode: 2,
+    });
+  }
+
+  const staging = path.join(skillsRoot, `.requestshield-${randomUUID()}.tmp`);
+  const backup = `${destination}.${randomUUID()}.backup`;
+  try {
+    if (deps.sourceDir) {
+      // Dùng trong test hoặc khi caller chỉ định source.
+      await cp(deps.sourceDir, staging, {
+        recursive: true,
+        errorOnExist: true,
+      });
+    } else if (isSea()) {
+      // SEA không có thư mục source trên disk, đọc skill đã nhúng.
+      await mkdir(staging);
+
+      await writeFile(
+          path.join(staging, "SKILL.md"),
+          Buffer.from(getAsset(skillAsset)),
+      );
+    } else {
+      // Chạy từ source/npm hoặc chạy bundle CJS trên disk.
+      //
+      // src/main.mjs                 -> ../skills/requestshield
+      // dist/requestshield.cjs      -> ../skills/requestshield
+      const executableDir = path.dirname(path.resolve(process.argv[1]));
+      const source = path.resolve(
+          executableDir,
+          "../skills/requestshield",
+      );
+
+      await cp(source, staging, {
+        recursive: true,
+        errorOnExist: true,
+      });
+    }
+    if (exists) await rename(destination, backup);
+    await rename(staging, destination);
+    if (exists) await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    if (await pathExists(backup)) {
+      await rm(destination, { recursive: true, force: true });
+      await rename(backup, destination);
+    }
+    throw error;
+  }
+  deps.log(`Installed RequestShield skill for Codex at ${destination}`);
+  deps.log("Restart Codex or start a new task before using the skill.");
+}
+
+/** @param {string} target */
+async function pathExists(target) {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/commands/keys-create.mjs

@@ -0,0 +1,46 @@
+// @ts-check
+
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { CliError } from "../errors.mjs";
+import { objectString } from "../api-client.mjs";
+
+/**
+ * @param {{ yes: boolean }} options
+ * @param {{ api: { rotateKeys(accessToken: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void, confirm?: () => Promise<boolean> }} deps
+ */
+export async function createKeys(options, deps) {
+  if (!options.yes) {
+    const accepted = await (deps.confirm ?? confirmRotation)();
+    if (!accepted) throw new CliError("Key rotation cancelled", { code: "CANCELLED", exitCode: 2 });
+  }
+  const token = await deps.sessions.loadToken();
+  const result = await deps.api.rotateKeys(token);
+  const appKey = objectString(result.body, "appKey");
+  const apiSecret = objectString(result.body, "apiSecret");
+  if (!appKey || !apiSecret) {
+    throw new CliError("The key rotation response did not contain appKey and apiSecret", {
+      code: "INVALID_RESPONSE",
+    });
+  }
+  deps.log("New RequestShield keys are active. Previous keys are deactivated.");
+  deps.log(`App Key: ${appKey}`);
+  deps.log(`Secret Key (shown once): ${apiSecret}`);
+  deps.log("Store the Secret Key in your backend secret manager now. The CLI did not save it.");
+}
+
+async function confirmRotation() {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new CliError("Refusing non-interactive key rotation without --yes", {
+      code: "CONFIRMATION_REQUIRED",
+      exitCode: 2,
+    });
+  }
+  const prompt = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await prompt.question("This deactivates the current keys. Type ROTATE to continue: ");
+    return answer === "ROTATE";
+  } finally {
+    prompt.close();
+  }
+}

package/src/commands/signin.mjs

@@ -0,0 +1,65 @@
+// @ts-check
+
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "../errors.mjs";
+import { objectString } from "../api-client.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
+ */
+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 });
+    }
+    if (code === "expired_token") break;
+    throw new CliError(objectString(result.body, "message") ?? "Sign-in failed", {
+      code: code ?? "SIGNIN_FAILED",
+      exitCode: 3,
+    });
+  }
+  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/errors.mjs

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

package/src/main.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { run } from "./cli.mjs";
+import { CliError } from "./errors.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();

package/src/session-store.mjs

@@ -0,0 +1,91 @@
+// @ts-check
+
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { CliError } from "./errors.mjs";
+
+export class SessionStore {
+  /** @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, homeDir?: string }} [options] */
+  constructor(options = {}) {
+    this.env = options.env ?? process.env;
+    this.platform = options.platform ?? process.platform;
+    this.homeDir = options.homeDir ?? os.homedir();
+    this.file = sessionPath(this.env, this.platform, this.homeDir);
+  }
+
+  /** @param {{ accessToken: string, account?: unknown }} session */
+  async save(session) {
+    if (!session.accessToken) throw new CliError("Cannot store an empty session token");
+    const directory = path.dirname(this.file);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temp = `${this.file}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, `${JSON.stringify(session)}\n`, { encoding: "utf8", mode: 0o600 });
+      await chmod(temp, 0o600);
+      await rename(temp, this.file);
+      await chmod(this.file, 0o600);
+      if (this.platform === "win32") restrictWindowsAcl(this.file);
+    } finally {
+      await rm(temp, { force: true });
+    }
+  }
+
+  async loadToken() {
+    const environmentToken = this.env.REQUESTSHIELD_ACCESS_TOKEN?.trim();
+    if (environmentToken) return environmentToken;
+    let contents;
+    try {
+      contents = await readFile(this.file, "utf8");
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") {
+        throw new CliError("Not signed in. Run `requestshield signin` first.", {
+          code: "NOT_SIGNED_IN",
+          exitCode: 3,
+        });
+      }
+      throw error;
+    }
+    let session;
+    try {
+      session = JSON.parse(contents);
+    } catch {
+      throw new CliError("The saved RequestShield session is invalid; sign in again", {
+        code: "INVALID_SESSION",
+        exitCode: 3,
+      });
+    }
+    const token = session && typeof session === "object" ? session.accessToken : undefined;
+    if (typeof token !== "string" || token === "") {
+      throw new CliError("The saved RequestShield session is invalid; sign in again", {
+        code: "INVALID_SESSION",
+        exitCode: 3,
+      });
+    }
+    return token;
+  }
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {NodeJS.Platform} platform @param {string} homeDir */
+export function sessionPath(env, platform, homeDir) {
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA || path.join(homeDir, "AppData", "Local"), "IntelliFend", "RequestShield", "session.json");
+  }
+  const base = env.XDG_STATE_HOME || path.join(homeDir, ".local", "state");
+  return path.join(base, "intellifend", "requestshield", "session.json");
+}
+
+/** @param {string} file */
+function restrictWindowsAcl(file) {
+  const result = spawnSync("icacls.exe", [file, "/inheritance:r", "/grant:r", `${process.env.USERNAME}:(R,W)`], {
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  if ((result.status ?? 1) !== 0) {
+    throw new CliError("The session was written but its Windows ACL could not be restricted; remove it and sign in again", {
+      code: "SESSION_PERMISSION_ERROR",
+    });
+  }
+}