requestshield 0.1.5 → 0.1.7

package/src/session-store.mjs

@@ -1,91 +1,204 @@
 // @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";
+import { getApiUrl, getOAuthConfig, validateBearerToken } from "./config.mjs";
+import { OAuthClient } from "./oauth-client.mjs";
+import { SessionFiles } from "./session-files.mjs";
+
+/** @typedef {{accessToken: string, refreshToken: string, expiresAt: number, scopes: string[]}} Credentials */
+/** @typedef {{issuer: string, clientId: string, apiUrl: string}} OAuthConfig */
+/** @typedef {Credentials & {version: 1, issuer: string, clientId: string, apiUrl: string, refreshState: "ready" | "in_progress"}} SavedSession */
+/** @typedef {'signed_out' | 'valid' | 'expired' | 'refresh_uncertain' | 'config_mismatch' | 'invalid' | 'configuration_error'} SessionState */
+/** @typedef {{profile: import('./config.mjs').Profile, apiUrl: string | null, issuer: string | null, clientId: string | null, state: SessionState, localOnly: true, expiresAt?: number, scopes?: string[]}} SessionStatus */
+
+const REFRESH_WINDOW_MS = 60_000;
 
 export class SessionStore {
-  /** @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, homeDir?: string }} [options] */
+  /**
+   * @param {{env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, homeDir?: string, profile?: import("./config.mjs").Profile,
+   * config?: OAuthConfig, oauth?: {refresh(token: string): Promise<Credentials>},
+   * now?: () => number, fs?: Partial<typeof import("node:fs/promises")>,
+   * protectPath?: (file: string, directory: boolean) => Promise<void>, lockWaitMs?: number}} [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);
+    this.profile = options.profile ?? "prod";
+    // Environment variables select OS storage locations only, never credentials
+    // or the API/provider configuration bound to those credentials.
+    this.file = sessionPath(options.env ?? process.env, this.platform, this.homeDir, this.profile);
+    this.config = options.config;
+    this.oauth = options.oauth;
+    this.now = options.now ?? Date.now;
+    this.files = new SessionFiles(this.file, {
+      platform: this.platform, fs: options.fs,
+      protectPath: options.protectPath, lockWaitMs: options.lockWaitMs,
+    });
   }
 
-  /** @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 });
-    }
+  /** A successful interactive sign-in replaces even an uncertain refresh record. @param {Credentials} credentials */
+  async save(credentials) {
+    const session = this.#record(credentials);
+    await this.files.withLock(async () => { await this.files.write(session); });
   }
 
-  async loadToken() {
-    const environmentToken = this.env.REQUESTSHIELD_ACCESS_TOKEN?.trim();
-    if (environmentToken) return environmentToken;
-    let contents;
+  /** Inspect the local snapshot only: no refresh, network request, lock or write.
+   * @returns {Promise<SessionStatus>}
+   */
+  async status() {
+    let config;
+    /** @type {SessionStatus} */
+    const result = { profile: this.profile, apiUrl: null, issuer: null, clientId: null, state: "signed_out", localOnly: true };
     try {
-      contents = await readFile(this.file, "utf8");
+      config = this.#config();
+      result.apiUrl = config.apiUrl;
+      result.issuer = config.issuer;
+      result.clientId = config.clientId;
     } 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;
+      if (!(error instanceof CliError) || error.code !== "OAUTH_CONFIG_INVALID") throw error;
+      try { result.apiUrl = getApiUrl(this.profile); } catch { /* Partial configuration may lack an API URL too. */ }
     }
     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,
-      });
+    try { session = checkedSession(await this.files.read()); }
+    catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      if (error.code === "NOT_SIGNED_IN") return result;
+      if (error.code === "INVALID_SESSION") return { ...result, state: "invalid" };
+      throw error;
     }
-    return token;
+    if (!config) return { ...result, state: "configuration_error" };
+    if (!matchesConfig(session, config)) return { ...result, state: "config_mismatch" };
+    return {
+      ...result,
+      state: session.refreshState === "in_progress" ? "refresh_uncertain" : session.expiresAt <= this.now() ? "expired" : "valid",
+      expiresAt: session.expiresAt,
+      scopes: [...session.scopes],
+    };
   }
-}
 
-/** @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");
+  /** Remove only this profile's local credential; never revoke provider tokens. */
+  async signout() {
+    return { profile: this.profile, removed: await this.files.remove() };
   }
-  const base = env.XDG_STATE_HOME || path.join(homeDir, ".local", "state");
-  return path.join(base, "intellifend", "requestshield", "session.json");
+
+  async loadToken() {
+    const initial = await this.#read();
+    if (initial.refreshState === "ready" && initial.expiresAt > this.now() + REFRESH_WINDOW_MS) return initial.accessToken;
+
+    return this.files.withLock(async () => {
+      // Another CLI process may have refreshed while this one waited.
+      const session = await this.#read();
+      this.#assertReady(session);
+      if (session.expiresAt > this.now() + REFRESH_WINDOW_MS) return session.accessToken;
+
+      // Persist before dispatch: a crash/lost response must not resend a
+      // potentially rotated refresh token. Preserve the original credential.
+      await this.files.write({ ...session, refreshState: "in_progress" });
+      let refreshed;
+      try {
+        const oauth = this.oauth ?? new OAuthClient({ config: this.#config() });
+        refreshed = await oauth.refresh(session.refreshToken);
+      } catch (error) {
+        const code = error instanceof CliError ? error.code : undefined;
+        if (code === "OAUTH_REJECTED" || code === "NETWORK_ERROR"
+          || code === "OAUTH_INVALID_RESPONSE" || code === "OAUTH_CONFIG_INVALID") {
+          // OAuthClient guarantees these are definitive rejections or failures
+          // during discovery, before refresh dispatch.
+          await this.files.write(session);
+          throw new CliError("Could not refresh the RequestShield session. Retry the command.", {
+            code: "SESSION_REFRESH_FAILED", exitCode: 7,
+          });
+        }
+        throw signinRequired();
+      }
+
+      // A validation/write failure retains the marker and original credentials.
+      const replacement = this.#record(refreshed);
+      await this.files.write(replacement);
+      return replacement.accessToken;
+    });
+  }
+
+  #config() { return this.config ?? getOAuthConfig(this.profile); }
+
+  /** @param {Credentials} value @returns {SavedSession} */
+  #record(value) {
+    const credentials = checkedCredentials(value);
+    if (credentials.expiresAt <= this.now()) throw invalidSession();
+    return { version: 1, ...this.#config(), ...credentials, refreshState: "ready" };
+  }
+
+  /** @returns {Promise<SavedSession>} */
+  async #read() {
+    const record = checkedSession(await this.files.read());
+    const config = this.#config();
+    if (!matchesConfig(record, config)) throw invalidSession();
+    return record;
+  }
+
+  /** @param {SavedSession} session */
+  #assertReady(session) {
+    if (session.refreshState !== "ready") throw signinRequired();
+  }
+}
+
+/** @param {SavedSession} session @param {OAuthConfig} config */
+function matchesConfig(session, config) {
+  return session.issuer === config.issuer && session.clientId === config.clientId && session.apiUrl === config.apiUrl;
+}
+
+/** @param {unknown} value @returns {SavedSession} */
+function checkedSession(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidSession();
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.version !== 1 || typeof record.issuer !== "string" || typeof record.clientId !== "string" || typeof record.apiUrl !== "string"
+    || (record.refreshState !== "ready" && record.refreshState !== "in_progress")) throw invalidSession();
+  const allowed = new Set(["version", "issuer", "clientId", "apiUrl", "refreshState",
+    "accessToken", "refreshToken", "expiresAt", "scopes"]);
+  if (Object.keys(record).some(key => !allowed.has(key))) throw invalidSession();
+  return { version: 1, issuer: record.issuer, clientId: record.clientId, apiUrl: record.apiUrl,
+    ...checkedCredentials(record), refreshState: record.refreshState };
 }
 
-/** @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,
+/** @param {unknown} value @returns {Credentials} */
+function checkedCredentials(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidSession();
+  const record = /** @type {Record<string, unknown>} */ (value);
+  try { validateBearerToken(record.accessToken); } catch { throw invalidSession(); }
+  if (typeof record.refreshToken !== "string" || record.refreshToken.length > 16_384
+    || !/^[\x21-\x7e]+$/.test(record.refreshToken)
+    || typeof record.expiresAt !== "number" || !Number.isSafeInteger(record.expiresAt) || record.expiresAt <= 0
+    || !Array.isArray(record.scopes) || record.scopes.length === 0 || record.scopes.length > 64
+    || record.scopes.some(scope => typeof scope !== "string" || !/^[\x21\x23-\x5b\x5d-\x7e]{1,256}$/.test(scope))
+    || new Set(record.scopes).size !== record.scopes.length) throw invalidSession();
+  return {
+    accessToken: /** @type {string} */ (record.accessToken), refreshToken: record.refreshToken,
+    expiresAt: record.expiresAt, scopes: [...record.scopes],
+  };
+}
+
+function invalidSession() {
+  return new CliError("The saved RequestShield session is invalid or belongs to different OAuth configuration. Run `requestshield signin` again.", {
+    code: "INVALID_SESSION", exitCode: 3,
   });
-  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",
-    });
+}
+function signinRequired() {
+  return new CliError("The RequestShield session could not be safely refreshed. Run `requestshield signin` again.", {
+    code: "SESSION_SIGNIN_REQUIRED", exitCode: 3,
+  });
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {NodeJS.Platform} platform @param {string} homeDir @param {import("./config.mjs").Profile} [profile] */
+export function sessionPath(env, platform, homeDir, profile = "prod") {
+  if (!["prod", "qat", "stg"].includes(profile)) {
+    throw new CliError("The RequestShield environment profile is invalid.", { code: "INVALID_PROFILE", exitCode: 2 });
   }
+  const suffix = profile === "prod" ? ["session.json"] : [profile, "session.json"];
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA || path.join(homeDir, "AppData", "Local"), "IntelliFend", "RequestShield", ...suffix);
+  }
+  const base = env.XDG_STATE_HOME || path.join(homeDir, ".local", "state");
+  return path.join(base, "intellifend", "requestshield", ...suffix);
 }

package/src/commands/billing-get.mjs

@@ -1,110 +0,0 @@
-// @ts-check
-
-import { CliError } from "../errors.mjs";
-import { objectString } from "../api-client.mjs";
-
-/**
- * @param {{ appKey: string }} options
- * @param {{ api: { getBilling(accessToken: string, appKey: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
- */
-export async function showBilling(options, deps) {
-  const accessToken =
-    await deps.sessions.loadToken();
-  
-  const result =
-    await deps.api.getBilling(accessToken, options.appKey);
-  
-  const billing = parseBilling(result.body);
-
-  deps.log(JSON.stringify({ ok: true, data: billing }, null, 2));
-}
-
-/** @param {unknown} body */
-function parseBilling(body) {
-  const ok = body && typeof body === "object" ?
-    Reflect.get(body, "ok") : undefined;
-  
-  const data = objectValue(body, "data");
-
-  const plan = objectValue(data, "plan");
-
-  const usage = objectValue(data, "usage");
-
-  if (ok !== true || !data || !plan || !usage) {
-    throw invalidResponse("The billing response did not contain ok=true, data.plan, and data.usage");
-  }
-
-  const tier = objectString(plan, "tier");
-  const currentCycle = Reflect.get(plan, "current_cycle");
-  const billing = Reflect.get(plan, "billing");
-  const nextCharge = objectString(plan, "next_charge");
-  const monthlyQuota = Reflect.get(usage, "monthly_quota");
-  const currentUsage = Reflect.get(usage, "current_usage");
-  const overageCharge = Reflect.get(usage, "overage_charge");
-
-  if (!tier) throw invalidResponse("The billing response did not contain plan.tier");
-  if (
-    !Array.isArray(currentCycle)
-    || currentCycle.length !== 2
-    || !currentCycle.every((value) =>
-      typeof value === "string" && isIsoDateTime(value))
-    || Date.parse(currentCycle[0]) > Date.parse(currentCycle[1])
-  ) {
-    throw invalidResponse("The billing response contained an invalid plan.current_cycle");
-  }
-  if (!nonNegativeNumber(billing)) {
-    throw invalidResponse("The billing response contained an invalid plan.billing");
-  }
-  if (!nextCharge || !isIsoDateTime(nextCharge)) {
-    throw invalidResponse("The billing response contained an invalid plan.next_charge");
-  }
-  if (!nonNegativeInteger(monthlyQuota) || !nonNegativeInteger(currentUsage)) {
-    throw invalidResponse("The billing response contained invalid quota or usage values");
-  }
-  if (!nonNegativeNumber(overageCharge)) {
-    throw invalidResponse("The billing response contained an invalid usage.overage_charge");
-  }
-
-  // Rebuild nested output so unexpected response fields cannot reach the terminal.
-  return {
-    plan: {
-      tier,
-      current_cycle: currentCycle,
-      billing,
-      next_charge: nextCharge,
-    },
-    usage: {
-      monthly_quota: monthlyQuota,
-      current_usage: currentUsage,
-      overage_charge: overageCharge,
-    },
-  };
-}
-
-/** @param {unknown} value @param {string} property */
-function objectValue(value, property) {
-  if (!value || typeof value !== "object") return undefined;
-  const found = Reflect.get(value, property);
-  return found && typeof found === "object" && !Array.isArray(found) ? found : undefined;
-}
-
-/** @param {unknown} value */
-function nonNegativeNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0;
-}
-
-/** @param {unknown} value */
-function nonNegativeInteger(value) {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-/** @param {string} value */
-function isIsoDateTime(value) {
-  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})?$/.test(value)
-    && Number.isFinite(Date.parse(value));
-}
-
-/** @param {string} message */
-function invalidResponse(message) {
-  return new CliError(message, { code: "INVALID_RESPONSE" });
-}

package/src/commands/challenge-volume.mjs

@@ -1,81 +0,0 @@
-// @ts-check
-
-import { CliError } from "../errors.mjs";
-import { objectString } from "../api-client.mjs";
-
-/**
- * @param {{ appKey: string, from?: string, to?: string, granularity?: string }} options
- * @param {{ api: { challengeVolume(accessToken: string, appKey: string, options: {from?: string, to?: string, granularity?: string}): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
- */
-export async function showChallengeVolume(options, deps) {
-  const accessToken = await deps.sessions.loadToken();
-  const filters = {
-    ...(options.from ? { from: options.from } : {}),
-    ...(options.to ? { to: options.to } : {}),
-    ...(options.granularity ? { granularity: options.granularity } : {}),
-  };
-  const result = await deps.api.challengeVolume(accessToken, options.appKey, filters);
-  const volume = parseChallengeVolume(result.body, options);
-  deps.log(JSON.stringify({ ok: true, data: volume }, null, 2));
-}
-
-/**
- * @param {unknown} body
- * @param {{ appKey: string, from?: string, to?: string, granularity?: string }} requested
- */
-function parseChallengeVolume(body, requested) {
-  const ok = body && typeof body === "object" ?
-    Reflect.get(body, "ok") : undefined;
-  
-  const data = body && typeof body === "object" ?
-    Reflect.get(body, "data") : undefined;
-  
-  if (ok !== true || !data || typeof data !== "object" || Array.isArray(data)) {
-    throw invalidResponse("The challenge volume response did not contain ok=true and data");
-  }
-
-  const appKey = objectString(data, "app_key");
-  const from = objectString(data, "from");
-  const to = objectString(data, "to");
-  const granularity = objectString(data, "granularity");
-  const challengeCount = Reflect.get(data, "challenge_count");
-  
-  if (appKey !== requested.appKey) {
-    throw invalidResponse("The challenge volume response did not match the requested App Key");
-  }
-  if (!from || !to || !isIsoTime(from) || !isIsoTime(to) || Date.parse(from) > Date.parse(to)) {
-    throw invalidResponse("The challenge volume response contained an invalid time range");
-  }
-  if (requested.from && Date.parse(from) !== Date.parse(requested.from)) {
-    throw invalidResponse("The challenge volume response did not match the requested start time");
-  }
-  if (requested.to && Date.parse(to) !== Date.parse(requested.to)) {
-    throw invalidResponse("The challenge volume response did not match the requested end time");
-  }
-  if (!granularity || (requested.granularity && granularity !== requested.granularity)) {
-    throw invalidResponse("The challenge volume response contained an unexpected granularity");
-  }
-  if (!Number.isSafeInteger(challengeCount) || /** @type {number} */ (challengeCount) < 0) {
-    throw invalidResponse("The challenge volume response contained an invalid challenge_count");
-  }
-
-  // Rebuild the response so unexpected API fields cannot reach command output.
-  return {
-    app_key: appKey,
-    from,
-    to,
-    granularity,
-    challenge_count: challengeCount,
-  };
-}
-
-/** @param {string} value */
-function isIsoTime(value) {
-  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
-    && Number.isFinite(Date.parse(value));
-}
-
-/** @param {string} message */
-function invalidResponse(message) {
-  return new CliError(message, { code: "INVALID_RESPONSE" });
-}

package/src/commands/contract.mjs

@@ -1,106 +0,0 @@
-// @ts-check
-
-import { CliError } from "../errors.mjs";
-import { objectString } from "../api-client.mjs";
-
-const SENSITIVE_FIELDS = new Set([
-  "access_token",
-  "accesstoken",
-  "api_secret",
-  "apisecret",
-  "secret_key",
-  "secretkey",
-  "session_token",
-  "sessiontoken",
-]);
-
-/**
- * @param {{ api: { integrationContract(accessToken: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
- */
-export async function showIntegrationContract(deps) {
-  const accessToken =
-    await deps.sessions.loadToken();
-  
-  const result =
-    await deps.api.integrationContract(accessToken);
-  
-  const data = parseIntegrationContract(result.body);
-
-  deps.log(JSON.stringify({ ok: true, data }, null, 2));
-}
-
-/** @param {unknown} body @returns {Record<string, unknown>} */
-function parseIntegrationContract(body) {
-  const ok = body && typeof body === "object" ?
-    Reflect.get(body, "ok") : undefined;
-  
-  const data = objectValue(body, "data");
-  if (ok !== true || !data) {
-    throw invalidResponse("The integration contract response did not contain ok=true and data");
-  }
-
-  const browser = objectValue(data, "browser");
-  const backend = objectValue(data, "backend");
-  const minJdk = backend ?
-    Reflect.get(backend, "min_jdk") : undefined;
-  
-  if (
-    !objectString(data, "contract_version")
-    || !browser
-    || !objectString(browser, "script_url")
-    || !objectString(browser, "token_header")
-    || !stringArray(browser, "available_modes")
-    || !backend
-    || !stringArray(backend, "supported_languages")
-    || !Number.isInteger(minJdk)
-    || /** @type {number} */ (minJdk) < 1
-    || !objectString(data, "release_state")
-  ) {
-    throw invalidResponse("The integration contract response is missing required fields");
-  }
-
-  // Preserve future contract fields, but never relay credential-shaped fields to output.
-  assertNoSensitiveFields(data);
-  return data;
-}
-
-/** @param {unknown} value @param {string} property */
-function objectValue(value, property) {
-  if (!value || typeof value !== "object")
-    return undefined;
-
-  const found = Reflect.get(value, property);
-
-  return found && typeof found === "object" && !Array.isArray(found) ? found : undefined;
-}
-
-/** @param {unknown} value @param {string} property */
-function stringArray(value, property) {
-  if (!value || typeof value !== "object")
-    return false;
-
-  const found = Reflect.get(value, property);
-
-  return Array.isArray(found) && found.every((item) => typeof item === "string" && item !== "");
-}
-
-/** @param {unknown} value */
-function assertNoSensitiveFields(value) {
-  if (Array.isArray(value)) {
-    for (const item of value) assertNoSensitiveFields(item);
-    return;
-  }
-  if (!value || typeof value !== "object")
-    return;
-  for (const [key, nestedValue] of Object.entries(value)) {
-    if (SENSITIVE_FIELDS.has(key.toLowerCase())) {
-      throw invalidResponse("The integration contract response contained a sensitive field");
-    }
-    assertNoSensitiveFields(nestedValue);
-  }
-}
-
-/** @param {string} message */
-function invalidResponse(message) {
-  return new CliError(message, { code: "INVALID_RESPONSE" });
-}