import type { TtscLintRuleSetting } from "../TtscLintRuleSetting";

/**
 * Security-focused TypeScript source rules from `eslint-plugin-security`.
 *
 * Reports likely security smells — non-literal sinks for eval, file I/O, regex
 * construction, child-process spawning, cryptographic primitives — that warrant
 * human review even if no exploit is statically provable.
 *
 * Treat findings as _hints_, not proofs.
 *
 * @reference https://github.com/eslint-community/eslint-plugin-security
 *
 * @evidence contracts/common.md#principled-implementation Named optional security policies use the severity-only union; the representation configures heuristic findings and does not encode a proof that an application is secure.
 * @evidence contracts/common.md#clear-and-simple-design One family groups source-level security concerns while common severity forms remain centralized outside the rule definitions.
 * @evidence contracts/common.md#prohibited-implementation-shortcuts Contract-defined sink-policy identifiers are explicit entries, without consumer exemptions or foreign API mutation in this configuration representation.
 * @evidence contracts/common.md#meaningful-documentation Native prose identifies findings as hints and member comments explain false-positive and fix boundaries; paragraph and member separation follow documentation guidance.
 */
export interface ITtscLintSecurityRules {
  /**
   * Detect Trojan-Source bidi control characters (U+202A, U+202E, ...) hidden
   * inside source.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-bidi-characters.md
   */
  "security/detect-bidi-characters"?: TtscLintRuleSetting;

  /**
   * Detect recognized Buffer-style read/write method names called with literal
   * `true` in the historical `noAssert` argument position.
   *
   * Receiver bindings and the installed Node version are not resolved; this is
   * a source-pattern policy rather than proof of unchecked memory access.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-buffer-noassert.md
   */
  "security/detect-buffer-noassert"?: TtscLintRuleSetting;

  /**
   * Detect `require("child_process")` / `require("node:child_process")` and
   * recognized `exec`/`execSync` calls whose command cannot be resolved as a
   * static expression. A bare ES import without a dynamic command is not
   * reported.
   *
   * Non-literal commands are the canonical shell-injection sink in Node
   * services.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-child-process.md
   */
  "security/detect-child-process"?: TtscLintRuleSetting;

  /**
   * Detect direct property assignments setting `.escapeMarkup = false`.
   * Object-literal options and other escaping API names are not inspected, and
   * the rule does not resolve the receiver to a particular template engine.
   *
   * When the property controls HTML escaping, disabling it can expose an XSS
   * sink for caller-controlled strings.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-disable-mustache-escape.md
   */
  "security/detect-disable-mustache-escape"?: TtscLintRuleSetting;

  /**
   * Detect `eval(...)` calls whose argument the native static-expression
   * recognizer cannot resolve.
   *
   * The rule flags the call shape, not proven caller control or taint.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-eval-with-expression.md
   */
  "security/detect-eval-with-expression"?: TtscLintRuleSetting;

  /**
   * Detect `new Buffer(input)` constructions with non-literal input —
   * historical source of allocation-disclosure bugs.
   *
   * The three successors — `Buffer.from`, `Buffer.alloc`, `Buffer.allocUnsafe`
   * — are offered as editor suggestions and none is applied automatically:
   * which one is correct depends on the argument, which this rule fires
   * precisely because it cannot read. The rule stays untagged because its
   * upstream-compatible name match also admits a user-defined constructor named
   * `Buffer`.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-new-buffer.md
   */
  "security/detect-new-buffer"?: TtscLintRuleSetting;

  /**
   * Detect a property call named `csrf` followed in source traversal by a
   * property call named `methodOverride`. The native check does not resolve
   * Express middleware registration, receiver identity, or execution order.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-no-csrf-before-method-override.md
   */
  "security/detect-no-csrf-before-method-override"?: TtscLintRuleSetting;

  /**
   * Detect `fs` calls (`readFile`, `writeFile`, `createReadStream`, ...) whose
   * filename argument cannot be resolved by the native static recognizer.
   *
   * Dynamic filenames are the standard path-traversal sink; sanitise or
   * allow-list before the call.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-non-literal-fs-filename.md
   */
  "security/detect-non-literal-fs-filename"?: TtscLintRuleSetting;

  /**
   * Detect `new RegExp(...)` and `RegExp(...)` calls whose pattern argument
   * cannot be resolved by the native static recognizer.
   *
   * Caller-controlled patterns can both trigger catastrophic backtracking and
   * let an attacker reshape the matcher to bypass intended validation.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-non-literal-regexp.md
   */
  "security/detect-non-literal-regexp"?: TtscLintRuleSetting;

  /**
   * Detect `require(...)` calls whose specifier the native static-expression
   * recognizer cannot resolve; this does not prove runtime caller control.
   *
   * A dynamic specifier lets caller-controlled data choose the module to load,
   * bypassing any module allow-list on Node.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-non-literal-require.md
   */
  "security/detect-non-literal-require"?: TtscLintRuleSetting;

  /**
   * Detect dynamic bracket-access such as `obj[req.body.x] = ...`, which can
   * let caller-controlled keys overwrite prototype-shaped properties or pull
   * out unintended fields.
   *
   * Fires on virtually any computed property access; expect a high
   * false-positive rate in normal application code.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-object-injection.md
   */
  "security/detect-object-injection"?: TtscLintRuleSetting;

  /**
   * Detect direct equality comparisons involving secret-like identifiers (`if
   * (token === expected)`) — use `crypto.timingSafeEqual` instead.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-possible-timing-attacks.md
   */
  "security/detect-possible-timing-attacks"?: TtscLintRuleSetting;

  /**
   * Detect `crypto.pseudoRandomBytes`, Node's deprecated alias of
   * `crypto.randomBytes`.
   *
   * Use the supported `crypto.randomBytes` name. The alias uses the same
   * cryptographically secure generator; this rule reports the deprecated name.
   *
   * Type-aware via the Checker, which resolves the object at the use site so an
   * automatic rewrite is never applied to a shadowed binding. Enabling this
   * rule therefore puts the whole run on the checker path. The diagnostic
   * itself stays name-based, so it still reports without one.
   *
   * The member name alone is rewritten to `randomBytes`. The edit is automatic
   * when the object is proven to be an import or require of Node `crypto`, and
   * an editor suggestion otherwise, because a local application object can also
   * be named `crypto`. That name-based diagnostic surface also keeps the rule
   * untagged.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-pseudoRandomBytes.md
   */
  "security/detect-pseudoRandomBytes"?: TtscLintRuleSetting;

  /**
   * Detect regex literals with catastrophic backtracking potential (ReDoS) —
   * typically nested or overlapping quantifiers over the same character set.
   *
   * Matching caller-controlled input against such a pattern can block the event
   * loop for seconds.
   *
   * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-unsafe-regex.md
   */
  "security/detect-unsafe-regex"?: TtscLintRuleSetting;
}