requestshield 0.1.4 → 0.1.6

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);
 }