requestshield 0.1.5 → 0.1.6

package/src/oauth-client.mjs

@@ -0,0 +1,153 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+import { validateOAuthConfig, REQUESTED_OAUTH_SCOPES, validateBearerToken, validatedUrl } from "./config.mjs";
+
+/** @typedef {{accessToken: string, refreshToken: string, expiresAt: number, scopes: string[]}} OAuthCredentials */
+/** @typedef {{authorizationEndpoint: string, tokenEndpoint: string}} OAuthDiscovery */
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+export class OAuthClient {
+  /** @param {{config: import('./config.mjs').OAuthConfig, fetchImpl?: typeof fetch, now?: () => number, timeoutMs?: number}} options */
+  constructor({config, fetchImpl = fetch, now = Date.now, timeoutMs = 15_000}) {
+    this.config = validateOAuthConfig(config);
+    this.fetchImpl = fetchImpl;
+    this.now = now;
+    this.timeoutMs = timeoutMs;
+    /** @type {OAuthDiscovery | undefined} */
+    this.discovery = undefined;
+  }
+
+  /** @param {{signal?: AbortSignal}} [options] @returns {Promise<OAuthDiscovery>} */
+  async discover({signal} = {}) {
+    signal?.throwIfAborted();
+    if (this.discovery) return this.discovery;
+    const {body} = await this.#request(`${this.config.issuer}/.well-known/openid-configuration`, {method: "GET"}, signal);
+    if (body.issuer !== this.config.issuer) throw invalidResponse();
+    let authorizationEndpoint, tokenEndpoint;
+    try {
+      authorizationEndpoint = validatedUrl(body.authorization_endpoint, "authorization endpoint");
+      tokenEndpoint = validatedUrl(body.token_endpoint, "token endpoint");
+    } catch { throw invalidResponse(); }
+    const tokenUrl = new URL(tokenEndpoint);
+    if (tokenUrl.protocol !== "https:" || tokenUrl.origin !== new URL(this.config.issuer).origin) throw invalidResponse();
+    if (!Array.isArray(body.response_types_supported) || !body.response_types_supported.includes("code")
+      || !Array.isArray(body.code_challenge_methods_supported) || !body.code_challenge_methods_supported.includes("S256")) throw invalidResponse();
+    this.discovery = {authorizationEndpoint, tokenEndpoint};
+    return this.discovery;
+  }
+
+  /** @param {{code: string, verifier: string, redirectUri: string, signal?: AbortSignal}} args @returns {Promise<OAuthCredentials>} */
+  async exchangeCode({code, verifier, redirectUri, signal}) {
+    const {tokenEndpoint} = await this.discover({signal});
+    const {body} = await this.#request(tokenEndpoint, {
+      method: "POST",
+      body: new URLSearchParams({grant_type: "authorization_code", client_id: this.config.clientId, code, code_verifier: verifier, redirect_uri: redirectUri}),
+    }, signal);
+    return this.#credentials(body);
+  }
+
+  /** Public refresh tokens rotate. Never retry a dispatched exchange. @param {string} refreshToken @returns {Promise<OAuthCredentials>} */
+  async refresh(refreshToken) {
+    const {tokenEndpoint} = await this.discover();
+    try {
+      const {body} = await this.#request(tokenEndpoint, {
+        method: "POST",
+        body: new URLSearchParams({grant_type: "refresh_token", client_id: this.config.clientId, refresh_token: refreshToken}),
+      });
+      return this.#credentials(body);
+    } catch (error) {
+      if (error instanceof CliError && ["OAUTH_INVALID_GRANT", "OAUTH_REJECTED"].includes(error.code)) throw error;
+      throw new CliError("The refresh result is uncertain; run `requestshield signin` again", {code: "OAUTH_REFRESH_UNCERTAIN", exitCode: 3});
+    }
+  }
+
+  /** @param {Record<string, unknown>} body @returns {OAuthCredentials} */
+  #credentials(body) {
+    let accessToken;
+    try { accessToken = validateBearerToken(body.access_token); } catch { throw invalidResponse(); }
+    const refreshToken = body.refresh_token;
+    if (typeof refreshToken !== "string" || !/^[\x21-\x7e]{1,16384}$/.test(refreshToken)
+      || typeof body.token_type !== "string" || body.token_type.toLowerCase() !== "bearer"
+      || typeof body.expires_in !== "number" || !Number.isSafeInteger(body.expires_in) || body.expires_in <= 0 || body.expires_in > 900
+      || typeof body.scope !== "string" || body.scope.length > 2048) throw invalidResponse();
+    const scopes = body.scope.split(" ");
+    if (new Set(scopes).size !== scopes.length || scopes.length !== REQUESTED_OAUTH_SCOPES.length
+      || !REQUESTED_OAUTH_SCOPES.every(scope => scopes.includes(scope))) throw invalidResponse();
+    return {accessToken, refreshToken, expiresAt: this.now() + body.expires_in * 1000, scopes};
+  }
+
+  /** @param {string} url @param {RequestInit} init @param {AbortSignal} [outerSignal] */
+  async #request(url, init, outerSignal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const timeout = setTimeout(abort, this.timeoutMs);
+    outerSignal?.addEventListener("abort", abort, {once: true});
+    if (outerSignal?.aborted) abort();
+    const signal = controller.signal;
+    let onAbort = () => {};
+    const cancelled = new Promise((_, reject) => {
+      onAbort = () => reject(new CliError("The identity provider could not be reached", {code: "NETWORK_ERROR", exitCode: 7}));
+      signal.addEventListener("abort", onAbort, {once: true});
+      if (signal.aborted) onAbort();
+    });
+    try {
+      const operation = (async () => {
+        signal.throwIfAborted();
+        const response = await this.fetchImpl(url, {
+          ...init, signal, redirect: "error", credentials: "omit", cache: "no-store",
+          headers: {Accept: "application/json", ...(init.body ? {"Content-Type": "application/x-www-form-urlencoded"} : {})},
+        });
+        if (response.status >= 300 && response.status < 400) throw invalidResponse();
+        if (!response.body || Number(response.headers.get("content-length")) > MAX_BODY_BYTES) {
+          void response.body?.cancel().catch(() => {});
+          throw invalidResponse();
+        }
+        const reader = response.body.getReader();
+        const cancelBody = () => { void reader.cancel().catch(() => {}); };
+        signal.addEventListener("abort", cancelBody, {once: true});
+        if (signal.aborted) cancelBody();
+        const chunks = [];
+        let size = 0;
+        try {
+          while (true) {
+            const {done, value} = await reader.read();
+            if (done) break;
+            size += value.length;
+            if (size > MAX_BODY_BYTES) { void reader.cancel().catch(() => {}); throw invalidResponse(); }
+            chunks.push(value);
+          }
+        } finally { signal.removeEventListener("abort", cancelBody); reader.releaseLock(); }
+        /** @type {Record<string, unknown>} */
+        let body;
+        try {
+          body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(Buffer.concat(chunks)));
+          if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error();
+        } catch { throw invalidResponse(); }
+        if (!response.ok) {
+          if (body.error === "invalid_grant" || ["idp_refresh_token_invalid", "idp_authorization_code_invalid", "invalid_grant"].includes(String(body.error_type))) {
+            throw new CliError("Authorization was rejected; run `requestshield signin` again", {code: "OAUTH_INVALID_GRANT", exitCode: 3});
+          }
+          if (response.status >= 400 && response.status < 500) {
+            throw new CliError("The identity provider rejected the request; check the OAuth configuration or sign in again", {code: "OAUTH_REJECTED", exitCode: 3});
+          }
+          throw new CliError("The identity provider is unavailable", {code: "NETWORK_ERROR", exitCode: 7});
+        }
+        return {body};
+      })();
+      return await Promise.race([operation, /** @type {Promise<never>} */ (cancelled)]);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw new CliError("The identity provider could not be reached", {code: "NETWORK_ERROR", exitCode: 7});
+    } finally {
+      clearTimeout(timeout);
+      signal.removeEventListener("abort", onAbort);
+      outerSignal?.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+}
+
+function invalidResponse() {
+  return new CliError("The identity provider returned an invalid OAuth response; check the provider configuration", {code: "OAUTH_INVALID_RESPONSE", exitCode: 3});
+}

package/src/oauth-loopback.mjs

@@ -0,0 +1,120 @@
+// @ts-check
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { CliError } from "./errors.mjs";
+
+/** @typedef {{code: string}} AuthorizationResult */
+
+/** Bind before returning, so opening the browser cannot race port allocation.
+ * @param {{state: string, issuer: string, signal: AbortSignal}} options
+ */
+export async function createLoopbackReceiver({state, issuer, signal}) {
+  /** @type {(value: AuthorizationResult) => void} */
+  let resolveResult;
+  /** @type {(error: Error) => void} */
+  let rejectResult;
+  const result = new Promise((resolve, reject) => { resolveResult = resolve; rejectResult = reject; });
+  // A callback can arrive while the OS browser launcher is still returning.
+  void result.catch(() => {});
+  /** @type {import('node:http').ServerResponse | undefined} */
+  let pendingResponse;
+  let accepted = false;
+  let expectedHost = "";
+  const server = createServer({maxHeaderSize: 8192, requestTimeout: 5_000, headersTimeout: 5_000}, (request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Connection", "close");
+    const hostCount = request.rawHeaders.filter((_, i) => i % 2 === 0 && request.rawHeaders[i].toLowerCase() === "host").length;
+    if (request.method !== "GET" || request.headers.host !== expectedHost || hostCount !== 1
+      || request.headers["transfer-encoding"] || (request.headers["content-length"] && request.headers["content-length"] !== "0")) {
+      response.writeHead(400).end("Invalid authorization callback."); return;
+    }
+    const raw = request.url ?? "";
+    if (raw.length > 8192 || raw.split("?")[0] !== "/callback") {
+      response.writeHead(404).end("Not found."); return;
+    }
+    let url;
+    try { url = new URL(raw, `http://${expectedHost}`); } catch {
+      response.writeHead(400).end("Invalid authorization callback."); return;
+    }
+    const params = url.searchParams;
+    const suppliedState = params.get("state") ?? "";
+    const code = params.get("code");
+    const error = params.get("error");
+    if (url.hash || [...params.keys()].some(key => params.getAll(key).length !== 1)
+      || !equalState(suppliedState, state)
+      || (params.has("iss") && params.get("iss") !== issuer)
+      || (code === null) === (error === null)
+      || (code !== null && !/^[\x21-\x7e]{1,4096}$/.test(code))
+      || (error !== null && !/^[A-Za-z_]{1,128}$/.test(error))) {
+      response.writeHead(400).end("Invalid authorization callback."); return;
+    }
+    if (accepted) { response.writeHead(409).end("Authorization callback already received."); return; }
+    accepted = true;
+    if (error !== null) {
+      response.writeHead(400).end("Authorization was not completed. Return to your terminal.");
+      rejectResult(new CliError("Sign-in was denied or cancelled", {code: "SIGNIN_DENIED", exitCode: 3}));
+      return;
+    }
+    // Keep this response pending until token exchange AND protected storage succeed.
+    pendingResponse = response;
+    resolveResult({code: /** @type {string} */ (code)});
+  });
+  server.maxConnections = 8;
+  server.on("clientError", (_error, socket) => {
+    if (socket.writable) socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+    else socket.destroy();
+  });
+  const aborted = () => {
+    rejectResult(new CliError("Sign-in was cancelled or expired; run `requestshield signin` again", {code: "SIGNIN_CANCELLED", exitCode: 3}));
+    if (pendingResponse && !pendingResponse.writableEnded) pendingResponse.writeHead(400).end("Sign-in was not completed. Return to your terminal.");
+    server.close();
+    server.closeAllConnections();
+  };
+  signal.addEventListener("abort", aborted, {once: true});
+  try {
+    if (signal.aborted) throw new Error();
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(undefined); });
+    });
+    if (signal.aborted) throw new Error();
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error();
+    expectedHost = `127.0.0.1:${address.port}`;
+  } catch {
+    signal.removeEventListener("abort", aborted);
+    server.close();
+    server.closeAllConnections();
+    throw new CliError("Could not start the local sign-in callback listener", {code: "SIGNIN_LISTENER_ERROR", exitCode: 3});
+  }
+  server.on("error", () => rejectResult(new CliError("The local sign-in listener failed", {code: "SIGNIN_LISTENER_ERROR", exitCode: 3})));
+  return {
+    redirectUri: `http://${expectedHost}/callback`,
+    result: /** @type {Promise<AuthorizationResult>} */ (result),
+    /** @param {boolean} success */
+    complete(success) {
+      if (!pendingResponse || pendingResponse.writableEnded) return;
+      pendingResponse.writeHead(success ? 200 : 400).end(success
+        ? "Signed in successfully. You may close this window and return to your terminal."
+        : "Sign-in was not completed. Return to your terminal.");
+    },
+    async close() {
+      signal.removeEventListener("abort", aborted);
+      if (!server.listening) return;
+      await new Promise(resolve => {
+        const timer = setTimeout(() => server.closeAllConnections(), 1000);
+        server.close(() => { clearTimeout(timer); resolve(undefined); });
+      });
+    },
+  };
+}
+
+/** @param {string} actual @param {string} expected */
+function equalState(actual, expected) {
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/src/session-files.mjs

@@ -0,0 +1,213 @@
+// @ts-check
+
+import * as nativeFs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "./errors.mjs";
+
+const MAX_SESSION_BYTES = 65_536;
+
+/** Filesystem errors never expose exception text that might contain credentials. */
+export class SessionFiles {
+  /** @param {string} file @param {{platform?: NodeJS.Platform, fs?: Partial<typeof nativeFs>, protectPath?: (file: string, directory: boolean) => Promise<void>, syncDirectory?: () => Promise<void>, lockWaitMs?: number}} [options] */
+  constructor(file, options = {}) {
+    this.file = file;
+    this.directory = path.dirname(file);
+    this.lock = `${file}.lock`;
+    this.fs = { ...nativeFs, ...options.fs };
+    this.platform = options.platform ?? process.platform;
+    this.protectPath = options.protectPath ?? ((file, directory) => this.#protect(file, directory));
+    this.syncDirectory = options.syncDirectory ?? (() => this.#syncDirectory());
+    this.lockWaitMs = options.lockWaitMs ?? 10_000;
+  }
+
+  /** @template T @param {() => Promise<T>} action @returns {Promise<T>} */
+  async withLock(action) {
+    await this.#prepareDirectory();
+    const deadline = performance.now() + this.lockWaitMs;
+    let handle;
+    while (!handle) {
+      try { handle = await this.fs.open(this.lock, "wx", 0o600); }
+      catch (error) {
+        if (errorCode(error) !== "EEXIST") throw storageFailure();
+        if (performance.now() >= deadline) {
+          throw new CliError("Another RequestShield command holds the session lock. Retry after it exits. If a command crashed, remove the session.json.lock file only after confirming no RequestShield command is running.", {
+            code: "SESSION_LOCKED", exitCode: 7,
+          });
+        }
+        await delay(40);
+      }
+    }
+    try {
+      // Never steal an old-looking lock: a suspended process may own it while
+      // its provider request rotates a token. No credentials enter this file.
+      await handle.writeFile(JSON.stringify({ pid: process.pid, id: randomUUID() }));
+      return await action();
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw storageFailure();
+    } finally {
+      await handle.close().catch(() => undefined);
+      await this.fs.rm(this.lock, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async read() {
+    let handle;
+    try {
+      const directory = await this.fs.lstat(this.directory);
+      if (!directory.isDirectory() || directory.isSymbolicLink()) throw storageFailure();
+      const stat = await this.fs.lstat(this.file);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw storageFailure();
+      if (this.platform !== "win32" && process.platform !== "win32"
+        && ((stat.mode & 0o077) !== 0 || (directory.mode & 0o077) !== 0
+          || stat.uid !== process.getuid?.() || directory.uid !== process.getuid?.())) throw permissionFailure();
+      handle = await this.fs.open(this.file, "r");
+      const buffer = Buffer.alloc(MAX_SESSION_BYTES + 1);
+      let total = 0;
+      while (total < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
+        if (bytesRead === 0) break;
+        total += bytesRead;
+      }
+      if (total > MAX_SESSION_BYTES) throw invalidFile();
+      try { return JSON.parse(buffer.subarray(0, total).toString("utf8")); }
+      catch { throw invalidFile(); }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (errorCode(error) === "ENOENT") {
+        throw new CliError("Not signed in. Run `requestshield signin` first.", { code: "NOT_SIGNED_IN", exitCode: 3 });
+      }
+      throw storageFailure();
+    } finally { await handle?.close().catch(() => undefined); }
+  }
+
+  /** Remove only the selected regular credential file under the refresh lock.
+   * No JSON parsing is needed, so malformed or mismatched sessions can be cleared.
+   */
+  async remove() {
+    try {
+      const directory = await this.fs.lstat(this.directory);
+      if (!directory.isDirectory() || directory.isSymbolicLink()) throw storageFailure();
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") return false;
+      if (error instanceof CliError) throw error;
+      throw storageFailure();
+    }
+    return this.withLock(async () => {
+      let removed = false;
+      try {
+        const existing = await this.fs.lstat(this.file);
+        if (!existing.isFile() || existing.isSymbolicLink()) throw storageFailure();
+        await this.fs.unlink(this.file);
+        removed = true;
+        await this.syncDirectory();
+        return true;
+      } catch (error) {
+        if (removed) {
+          throw new CliError("The local session was removed, but its durability could not be confirmed. Run `requestshield signout` again to confirm removal.", {
+            code: "SESSION_COMMIT_UNCERTAIN", exitCode: 7,
+          });
+        }
+        if (errorCode(error) === "ENOENT") return false;
+        if (error instanceof CliError) throw error;
+        throw storageFailure();
+      }
+    });
+  }
+
+  /** Caller holds the session lock. @param {unknown} value */
+  async write(value) {
+    const temp = `${this.file}.${randomUUID()}.tmp`;
+    let handle;
+    let replaced = false;
+    try {
+      try {
+        const existing = await this.fs.lstat(this.file);
+        if (!existing.isFile() || existing.isSymbolicLink()) throw storageFailure();
+      } catch (error) { if (errorCode(error) !== "ENOENT") throw error; }
+      handle = await this.fs.open(temp, "wx", 0o600);
+      await this.protectPath(temp, false);
+      const serialized = `${JSON.stringify(value)}\n`;
+      if (Buffer.byteLength(serialized) > MAX_SESSION_BYTES) throw invalidFile();
+      await handle.writeFile(serialized, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await this.fs.rename(temp, this.file);
+      replaced = true;
+      await this.syncDirectory();
+    } catch (error) {
+      if (replaced) {
+        throw new CliError("The session was replaced, but its durability could not be confirmed. Run `requestshield signin` again if the next command cannot load it.", {
+          code: "SESSION_COMMIT_UNCERTAIN", exitCode: 7,
+        });
+      }
+      if (error instanceof CliError) throw error;
+      throw storageFailure();
+    } finally {
+      await handle?.close().catch(() => undefined);
+      await this.fs.rm(temp, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async #prepareDirectory() {
+    try {
+      await this.fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+      const stat = await this.fs.lstat(this.directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw permissionFailure();
+      await this.protectPath(this.directory, true);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw permissionFailure();
+    }
+  }
+
+  async #syncDirectory() {
+    if (this.platform === "win32" || process.platform === "win32") return;
+    const directory = await this.fs.open(this.directory, "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  }
+
+  /** @param {string} file @param {boolean} directory */
+  async #protect(file, directory) {
+    try {
+      if (this.platform !== "win32") {
+        await this.fs.chmod(file, directory ? 0o700 : 0o600);
+        return;
+      }
+      // Static script, path in environment, current SID avoids domain lookup.
+      const script = [
+        '$ErrorActionPreference = "Stop"',
+        '$sessionSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User',
+        `$sessionAcl = New-Object System.Security.AccessControl.${directory ? "DirectorySecurity" : "FileSecurity"}`,
+        '$sessionAcl.SetOwner($sessionSid)',
+        '$sessionAcl.SetAccessRuleProtection($true, $false)',
+        directory
+          ? '$sessionRule = New-Object System.Security.AccessControl.FileSystemAccessRule($sessionSid, "FullControl", "ContainerInherit,ObjectInherit", "None", "Allow")'
+          : '$sessionRule = New-Object System.Security.AccessControl.FileSystemAccessRule($sessionSid, "FullControl", "Allow")',
+        '$sessionAcl.AddAccessRule($sessionRule)',
+        `[System.IO.${directory ? "Directory" : "File"}]::SetAccessControl($env:REQUESTSHIELD_SESSION_ACL_PATH, $sessionAcl)`,
+      ].join("\n");
+      await promisify(execFile)("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+        windowsHide: true, timeout: 10_000,
+        env: { SystemRoot: process.env.SystemRoot, PATH: process.env.PATH, REQUESTSHIELD_SESSION_ACL_PATH: file },
+      });
+    } catch { throw permissionFailure(); }
+  }
+}
+
+/** @param {unknown} error */
+function errorCode(error) { return error && typeof error === "object" ? Reflect.get(error, "code") : undefined; }
+function storageFailure() {
+  return new CliError("Could not read or safely save the RequestShield session. Check local storage permissions and sign in again if a refresh was interrupted.", { code: "SESSION_STORAGE_ERROR", exitCode: 7 });
+}
+function permissionFailure() {
+  return new CliError("Could not protect the RequestShield session for the current operating-system user. No new credentials were written.", { code: "SESSION_PERMISSION_ERROR", exitCode: 7 });
+}
+function invalidFile() {
+  return new CliError("The saved RequestShield session is invalid. Run `requestshield signin` again.", { code: "INVALID_SESSION", exitCode: 3 });
+}