// Detecting a scope-insufficient upstream rejection. A 403 that means "this
// grant does not cover that operation" is unfixable by re-running the same
// OAuth flow, so it must not be labelled connection_rejected (whose recovery
// tells the agent to re-authenticate). Providers signal it three ways:
//
//   - RFC 6750: a `WWW-Authenticate: Bearer error="insufficient_scope"
//     scope="..."` challenge header (the `scope` attribute names what the
//     request needed).
//   - Google (google.rpc.ErrorInfo): a JSON body whose error details carry
//     `reason: "ACCESS_TOKEN_SCOPE_INSUFFICIENT"`.
//   - Generic OAuth JSON: `{ "error": "insufficient_scope" }` (RFC 6750 §3.1
//     as a body, which some providers emit instead of the header).
//
// Detection is deliberately strict — a false positive strips the
// re-authenticate recovery from a 403 that re-auth WOULD fix:
//
//   - Challenge headers are PARSED into parameters (quoted values consumed
//     whole), so `error=insufficient_scope` inside another parameter's
//     quoted value never counts; only the `error` parameter's own exact
//     value does.
//   - Structured bodies match only exact `error` / `reason` field values.
//   - Text bodies are JSON-parsed first and then inspected structurally;
//     non-JSON text never classifies (prose mentioning the tokens misses).
//
// A miss is benign: the failure stays on the existing classification.

export type InsufficientScopeDetection = {
  /** Scopes the upstream named as required, when it named any (RFC 6750's
   *  `scope` attribute). Empty when the provider only signalled the class of
   *  failure (Google's ErrorInfo does not carry the missing scope). */
  readonly requiredScopes: readonly string[];
};

const MAX_DEPTH = 8;

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

/** Parser for the whole WWW-Authenticate header per RFC 7235 §2.1: a
 *  comma-separated #list of challenges, each
 *  `scheme [ 1*SP ( token68 / #auth-param ) ]`. Implemented as an explicit
 *  per-challenge state machine so params can never attach across challenge
 *  boundaries or to a token68 credential:
 *
 *  - "scheme": just read a scheme; accepts a token68 OR a first auth-param
 *    (space-separated, no comma).
 *  - "params": accepts further auth-params ONLY after a comma.
 *  - "token68": accepts nothing; any trailing param is malformed.
 *
 *  Auth-params allow BWS around `=` (RFC 7230). Quoted-strings consume
 *  quoted-pairs whole and must end at a separator. ANY malformed shape —
 *  scheme-less params, space-separated param runs, params after token68,
 *  stray quotes/bytes — returns null and never classifies: a miss is benign,
 *  a false positive strips a valid recovery path. */
type Challenge = { readonly scheme: string; readonly params: Map<string, string> };

// HTTP `token` alphabet (RFC 7230 §3.2.6) — schemes and auth-param names.
const TOKEN_RE = /[A-Za-z0-9!#$%&'*+.^_`|~-]/;
// token68 alphabet (RFC 7235 §2.1), padding `=` handled separately.
const TOKEN68_RE = /[A-Za-z0-9._~+/-]/;
// Superset used by the word reader; each use site validates against the
// context-specific alphabet after reading.
const WORD_RE = /[A-Za-z0-9!#$%&'*+.^_`|~/-]/;

const isToken = (word: string): boolean => [...word].every((ch) => TOKEN_RE.test(ch));
// Unquoted URL values some providers emit (scheme://host/path?query): URI
// characters per RFC 3986, no whitespace/comma/quotes.
const isUrlish = (word: string): boolean => /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s,"]+$/.test(word);
const isToken68 = (word: string): boolean => [...word].every((ch) => TOKEN68_RE.test(ch));

const parseChallenges = (header: string): readonly Challenge[] | null => {
  const len = header.length;
  const challenges: Challenge[] = [];
  let current: Challenge | null = null;
  let state: "boundary" | "scheme" | "token68" | "params" = "boundary";
  let sawComma = true; // header start counts as a list boundary
  let i = 0;

  const readWord = (): string => {
    const start = i;
    while (i < len && WORD_RE.test(header[i]!)) i += 1;
    return header.slice(start, i);
  };
  // Returns null on an unterminated quote or a quote run into the next token.
  const readQuoted = (): string | null => {
    let value = "";
    i += 1; // opening quote
    while (i < len) {
      const ch = header[i]!;
      if (ch === '"') {
        i += 1;
        return i >= len || /[\s,]/.test(header[i]!) ? value : null;
      }
      if (ch === "\\" && i + 1 < len) {
        value += header[i + 1];
        i += 2;
        continue;
      }
      value += ch;
      i += 1;
    }
    return null; // unterminated
  };

  while (i < len) {
    while (i < len && /\s/.test(header[i]!)) i += 1;
    if (i >= len) break;
    if (header[i] === ",") {
      sawComma = true;
      i += 1;
      continue;
    }
    if (!WORD_RE.test(header[i]!)) return null; // stray quote/byte: malformed
    const word = readWord();
    // Look ahead through BWS for `=` to classify the word.
    let j = i;
    while (j < len && /[ \t]/.test(header[j]!)) j += 1;
    const isPaddingRun = (() => {
      // An `=`-run directly on the word (no BWS) that is followed (after
      // optional whitespace) by a comma or the end of input is token68
      // padding. An `=` followed by a value — even across BWS — is an
      // auth-param (RFC 7230 allows BWS around `=`).
      if (header[i] !== "=") return false;
      let k = i;
      while (k < len && header[k] === "=") k += 1;
      while (k < len && /[ \t]/.test(header[k]!)) k += 1;
      return k >= len || header[k] === ",";
    })();

    if (isPaddingRun) {
      // token68 with padding — only legal directly after a scheme.
      if (state !== "scheme" || sawComma) return null;
      if (!isToken68(word)) return null;
      while (i < len && header[i] === "=") i += 1;
      state = "token68";
      sawComma = false;
      continue;
    }

    if (header[j] === "=") {
      // auth-param: `word BWS = BWS value`.
      if (!isToken(word)) return null; // param name must be an HTTP token
      if (current === null) return null; // scheme-less param
      if (state === "token68") return null; // params after token68
      if (state === "scheme" && sawComma) return null; // "Bearer, a=b"
      if (state === "params" && !sawComma) return null; // space-separated run
      i = j + 1;
      while (i < len && /[ \t]/.test(header[i]!)) i += 1;
      let value: string;
      if (header[i] === '"') {
        const quoted = readQuoted();
        if (quoted === null) return null;
        value = quoted;
      } else {
        const start = i;
        while (i < len && !/[\s,]/.test(header[i]!)) i += 1;
        value = header.slice(start, i);
        // An unquoted value must be an HTTP token (`realm =,` / `realm=;`
        // are malformed) — EXCEPT that real providers emit unquoted URLs for
        // resource_metadata (observed live: Stripe), so URL-safe characters
        // are tolerated there. The signal params (`error`, `scope`) stay
        // token-strict.
        if (value.length === 0) return null;
        const lowerName = word.toLowerCase();
        if (!isToken(value) && !(lowerName === "resource_metadata" && isUrlish(value))) {
          return null;
        }
      }
      // Duplicate SIGNAL params (`error`, `scope`) within one challenge mean
      // a header playing games — never classify. Other duplicates are
      // tolerated first-wins: real providers emit them (observed live:
      // Sentry duplicates resource_metadata).
      const key = word.toLowerCase();
      if (current.params.has(key)) {
        if (key === "error" || key === "scope") return null;
      } else {
        current.params.set(key, value);
      }
      state = "params";
      sawComma = false;
      continue;
    }

    // Bare word: a new challenge's scheme at a list boundary, a token68
    // directly after a scheme, malformed anywhere else.
    if (sawComma) {
      if (!isToken(word)) return null; // a scheme must be an HTTP token
      current = { scheme: word.toLowerCase(), params: new Map() };
      challenges.push(current);
      state = "scheme";
      sawComma = false;
      continue;
    }
    if (state === "scheme") {
      if (!isToken68(word)) return null;
      state = "token68";
      continue;
    }
    return null;
  }

  return challenges;
};

const detectFromChallenge = (header: string): InsufficientScopeDetection | null => {
  const challenges = parseChallenges(header);
  if (challenges === null) return null;
  for (const challenge of challenges) {
    if (challenge.scheme !== "bearer") continue;
    if (challenge.params.get("error") !== "insufficient_scope") continue;
    const scope = challenge.params.get("scope");
    return { requiredScopes: scope ? scope.split(/\s+/).filter(Boolean) : [] };
  }
  return null;
};

const detectFromStructured = (body: unknown, depth: number): boolean => {
  if (depth > MAX_DEPTH) return false;
  if (Array.isArray(body)) {
    return body.some((item) => detectFromStructured(item, depth + 1));
  }
  if (!isRecord(body)) return false;
  if (body.error === "insufficient_scope") return true;
  if (body.reason === "ACCESS_TOKEN_SCOPE_INSUFFICIENT") return true;
  // Recurse into records/arrays only — nested strings are data (scope lists,
  // docs prose), never the error envelope itself.
  return Object.values(body).some(
    (value) => (isRecord(value) || Array.isArray(value)) && detectFromStructured(value, depth + 1),
  );
};

const parseJsonSafe = (text: string): unknown => {
  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: classifying an untrusted upstream error body; a parse failure just means "not a JSON body", never an error path
  try {
    // oxlint-disable-next-line executor/no-json-parse -- boundary: same untrusted-body classification; the parsed value is only structurally inspected, never decoded into domain types
    return JSON.parse(text) as unknown;
  } catch {
    return undefined;
  }
};

const detectFromBody = (body: unknown): boolean => {
  if (typeof body === "string") {
    const parsed = parseJsonSafe(body);
    return parsed !== undefined && detectFromStructured(parsed, 0);
  }
  return detectFromStructured(body, 0);
};

/** Strict detection over a text fragment whose JSON body survives only as a
 *  suffix of a transport error message (the MCP SDK embeds the failed POST's
 *  body after a fixed prefix). The JSON is isolated from the first `{` or `[`
 *  and parsed; prose without a parseable JSON envelope never classifies. */
export const insufficientScopeFromEmbeddedJson = (text: string): boolean => {
  const start = text.search(/[{[]/);
  if (start < 0) return false;
  const parsed = parseJsonSafe(text.slice(start));
  return parsed !== undefined && detectFromStructured(parsed, 0);
};

/** Inspect an upstream 401/403's body and headers for a scope-insufficiency
 *  signal. Returns `null` when nothing matches, so callers fall through to
 *  their existing classification. */
export const detectInsufficientScope = (input: {
  readonly body?: unknown;
  readonly headers?: Record<string, string>;
}): InsufficientScopeDetection | null => {
  for (const [name, value] of Object.entries(input.headers ?? {})) {
    if (name.toLowerCase() !== "www-authenticate") continue;
    const detected = detectFromChallenge(value);
    if (detected) return detected;
  }
  return detectFromBody(input.body) ? { requiredScopes: [] } : null;
};