Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

10.1 KB
Raw Blame
import type { TokenResponse } from "./types";
import {
  REFRESH_COOKIE_LOCK,
  browserCoordinationAvailable,
  captureSession,
  invalidateSession,
  isSessionCurrent,
  markSessionUnavailable,
  readCoordinationRecord,
  replaceSessionIfCurrent,
  type CoordinationRecord,
  type SessionSnapshot
} from "./session";

const CSRF_HEADER = "X-ARES-CSRF";
const CSRF_COOKIE_NAMES = ["__Host-ares-csrf", "ares-dev-csrf"] as const;
const CSRF_PATTERN = /^[A-Za-z0-9_-]{43}$/;

export class ApiError extends Error {
  readonly status: number;
  readonly detail: unknown;

  constructor(status: number, detail: unknown) {
    super(typeof detail === "string" ? detail : `Request failed with ${status}`);
    this.status = status;
    this.detail = detail;
  }
}

async function parseResponse(response: Response): Promise<unknown> {
  const text = await response.text();
  if (!text) {
    return null;
  }
  try {
    return JSON.parse(text);
  } catch {
    return text;
  }
}

function errorDetail(body: unknown): unknown {
  if (typeof body === "object" && body !== null && "detail" in body) {
    return body.detail ?? body;
  }
  return body;
}

function validTokenResponse(value: unknown): value is TokenResponse {
  return (
    typeof value === "object"
    && value !== null
    && "access_token" in value
    && typeof value.access_token === "string"
    && value.access_token.length > 0
    && !("refresh_token" in value)
    && "session_coordination_key" in value
    && typeof value.session_coordination_key === "string"
    && /^[A-Za-z0-9_-]{43}$/.test(value.session_coordination_key)
    && "refresh_generation" in value
    && typeof value.refresh_generation === "number"
    && Number.isSafeInteger(value.refresh_generation)
    && value.refresh_generation >= 0
  );
}

export function readBrowserCsrfToken(): string | null {
  let source: string;
  try {
    source = document.cookie;
  } catch {
    return null;
  }
  const found: string[] = [];
  for (const item of source.split(";")) {
    const separator = item.indexOf("=");
    if (separator < 1) {
      continue;
    }
    const name = item.slice(0, separator).trim();
    const value = item.slice(separator + 1);
    if ((CSRF_COOKIE_NAMES as readonly string[]).includes(name)) {
      found.push(value);
    }
  }
  source = "";
  return found.length === 1 && CSRF_PATTERN.test(found[0]) ? found[0] : null;
}

export async function bootstrapBrowserCsrf(): Promise<void> {
  const response = await fetch("/auth/csrf", {
    method: "GET",
    credentials: "same-origin",
    cache: "no-store"
  });
  if (response.status !== 204) {
    const body = await parseResponse(response);
    throw new ApiError(response.status, errorDetail(body));
  }
}

async function requireBrowserCsrf(): Promise<string> {
  let value = readBrowserCsrfToken();
  if (value === null) {
    await bootstrapBrowserCsrf();
    value = readBrowserCsrfToken();
  }
  if (value === null) {
    throw new ApiError(403, "Browser request rejected");
  }
  return value;
}

export async function withRefreshCookieLock<T>(operation: () => Promise<T>): Promise<T> {
  if (!browserCoordinationAvailable()) {
    throw new ApiError(401, "Browser session coordination unavailable");
  }
  return navigator.locks.request(REFRESH_COOKIE_LOCK, operation);
}

async function browserMutationResponse(
  path: string,
  init: RequestInit,
  options: { authenticated: boolean }
): Promise<Response> {
  const csrf = await requireBrowserCsrf();
  const headers = new Headers(init.headers);
  headers.set(CSRF_HEADER, csrf);
  const requestInit = {
    ...init,
    method: "POST",
    credentials: "same-origin" as RequestCredentials,
    cache: "no-store" as RequestCache,
    headers
  };
  return options.authenticated
    ? fetchWithSession(path, requestInit, false)
    : fetch(path, requestInit);
}

export async function browserMutationRequest<T>(
  path: string,
  init: RequestInit = {},
  options: { authenticated?: boolean } = {}
): Promise<T> {
  const response = await browserMutationResponse(path, init, {
    authenticated: options.authenticated ?? false
  });
  const body = await parseResponse(response);
  if (!response.ok) {
    throw new ApiError(response.status, errorDetail(body));
  }
  return body as T;
}

interface RefreshFlight {
  readonly revision: number;
  promise: Promise<boolean>;
}

let refreshFlight: RefreshFlight | null = null;
const INVALID_EXPECTATION = Symbol("invalid-refresh-expectation");

function refreshExpectation(
  snapshot: SessionSnapshot
): CoordinationRecord | null | typeof INVALID_EXPECTATION {
  const shared = readCoordinationRecord();
  if (shared === null) {
    return snapshot.coordinationKey === null ? null : INVALID_EXPECTATION;
  }
  if (shared.tombstone) {
    return INVALID_EXPECTATION;
  }
  if (
    snapshot.coordinationKey !== null
    && (shared.key !== snapshot.coordinationKey
      || snapshot.refreshGeneration === null
      || shared.generation < snapshot.refreshGeneration)
  ) {
    return INVALID_EXPECTATION;
  }
  return shared;
}

async function settleIndeterminateRefresh(snapshot: SessionSnapshot): Promise<void> {
  invalidateSession(snapshot);
  try {
    await browserMutationResponse("/auth/logout", {}, { authenticated: false });
  } catch {
    // Reauthentication is mandatory; no refresh or logout retry loop is permitted.
  }
}

async function performRefresh(snapshot: SessionSnapshot): Promise<boolean> {
  if (!isSessionCurrent(snapshot)) {
    return false;
  }
  const expected = refreshExpectation(snapshot);
  if (expected === INVALID_EXPECTATION) {
    invalidateSession(snapshot);
    return false;
  }
  try {
    const response = await browserMutationResponse("/auth/refresh", {}, {
      authenticated: false
    });
    if (!response.ok) {
      if (response.status === 503) {
        markSessionUnavailable(snapshot);
      } else {
        invalidateSession(snapshot);
      }
      return false;
    }
    const body = await parseResponse(response);
    if (!validTokenResponse(body)) {
      invalidateSession(snapshot);
      return false;
    }
    if (
      expected !== null
      && (body.session_coordination_key !== expected.key
        || body.refresh_generation !== expected.generation + 1)
    ) {
      invalidateSession(snapshot);
      return false;
    }
    return replaceSessionIfCurrent(
      snapshot,
      body.access_token,
      body.session_coordination_key,
      body.refresh_generation
    );
  } catch (error) {
    if (error instanceof ApiError) {
      if (error.status === 503) {
        markSessionUnavailable(snapshot);
      } else {
        invalidateSession(snapshot);
      }
      return false;
    }
    await settleIndeterminateRefresh(snapshot);
    return false;
  }
}

export function refreshAccessToken(snapshot = captureSession()): Promise<boolean> {
  if (!browserCoordinationAvailable()) {
    invalidateSession(snapshot);
    return Promise.resolve(false);
  }
  if (refreshFlight && refreshFlight.revision === snapshot.revision) {
    return refreshFlight.promise;
  }
  const flight: RefreshFlight = {
    revision: snapshot.revision,
    promise: Promise.resolve(false)
  };
  flight.promise = withRefreshCookieLock(() => performRefresh(snapshot)).finally(() => {
    if (refreshFlight === flight) {
      refreshFlight = null;
    }
  });
  refreshFlight = flight;
  return flight.promise;
}

function sessionChangedError(): ApiError {
  return new ApiError(401, "Session changed");
}

async function fetchWithSession(
  path: string,
  init: RequestInit,
  retry: boolean,
  snapshot = captureSession()
): Promise<Response> {
  const headers = new Headers(init.headers);
  if (snapshot.accessToken) {
    headers.set("Authorization", `Bearer ${snapshot.accessToken}`);
  }
  // Attach the double-submit CSRF header on EVERY state-changing request, not only
  // the /auth/* flows that go through browserMutationRequest. The API authenticates
  // via the Bearer header, but the session/refresh cookies still ride along on
  // same-origin requests (credentials: "same-origin"); requiring X-ARES-CSRF on all
  // mutations closes the gap where a cookie-accepting endpoint could be driven from
  // a cross-site form. A cross-site attacker cannot read the __Host- CSRF cookie to
  // replicate this header, so the server-side header↔cookie compare rejects the
  // forgery. (AUDIT run-1 C5)
  const method = (init.method ?? "GET").toUpperCase();
  const isMutation = method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
  if (isMutation && !headers.has(CSRF_HEADER)) {
    let csrf = readBrowserCsrfToken();
    if (!csrf) {
      try {
        await bootstrapBrowserCsrf();
        csrf = readBrowserCsrfToken();
      } catch {
        csrf = null;
      }
    }
    if (csrf) {
      headers.set(CSRF_HEADER, csrf);
    }
  }
  const response = await fetch(path, {
    ...init,
    credentials: "same-origin",
    headers
  });

  if (snapshot.accessToken && !isSessionCurrent(snapshot)) {
    throw sessionChangedError();
  }
  if (response.status !== 401) {
    return response;
  }
  if (!retry) {
    if (snapshot.accessToken) {
      invalidateSession(snapshot);
    }
    return response;
  }
  const current = captureSession();
  if (!isSessionCurrent(snapshot)) {
    throw sessionChangedError();
  }
  if (current.accessToken && current.accessToken !== snapshot.accessToken) {
    return fetchWithSession(path, init, false, current);
  }
  if (await refreshAccessToken(current)) {
    const refreshed = captureSession();
    if (!isSessionCurrent(snapshot)) {
      throw sessionChangedError();
    }
    return fetchWithSession(path, init, false, refreshed);
  }
  return response;
}

export async function apiRequest<T>(
  path: string,
  init: RequestInit = {},
  retry = true
): Promise<T> {
  const response = await fetchWithSession(path, init, retry);
  const body = await parseResponse(response);
  if (!response.ok) {
    throw new ApiError(response.status, errorDetail(body));
  }
  return body as T;
}

export async function apiBlobRequest(
  path: string,
  init: RequestInit = {},
  retry = true
): Promise<Blob> {
  const response = await fetchWithSession(path, init, retry);
  if (!response.ok) {
    const body = await parseResponse(response);
    throw new ApiError(response.status, errorDetail(body));
  }
  return response.blob();
}