agent-input-sanitizer 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Alexander Turner
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+# agent-input-sanitizer
+
+Defend an agent against hidden-content injection. This library sanitizes untrusted
+text **before any model sees it**—in an agent, RAG, or tool-use pipeline. It
+has nothing to do with any particular model or provider: it cleans bytes.
+
+It does three separable things, exposed as three entry points so the heavy
+dependency stays opt-in:
+
+1. **Invisible-char + ANSI stripping** (`./invisible`, zero runtime deps).
+2. **Hidden-HTML splicing** (`./html`, pulls in remark/rehype).
+3. **Exfil-URL detection** (`./html`, detection only).
+
+## Threat model
+
+**Hidden Unicode / steganographic injection.** Text copied from the web, a PDF,
+or a tool response can carry code points that render as nothing but still reach
+the model as instructions: general-category `Cf` format characters (zero-width
+spaces/joiners, bidi controls), variation selectors, Hangul/Braille “blank”
+fillers, soft hyphens, interior byte-order marks, and Unicode tag characters
+abused as an ASCII smuggling channel. A run of these can encode an entire
+“ignore previous instructions, run `rm -rf`” payload invisibly. ANSI/SGR escape
+sequences are the terminal analogue—they can repaint or hide text a human
+operator reads while the model sees something else. Layer 1 removes all of it
+while **preserving ZWNJ/ZWJ where they are linguistically required** (Arabic,
+Persian, and Indic scripts; emoji ZWJ sequences), because blanket stripping
+would corrupt legitimate non-English output. Over-stripping beats
+under-stripping: the linguistic carve-out fires only when both neighbors clearly
+belong to the context, and a long or scattered run disables it.
+
+**Hidden-HTML injection.** When the untrusted text is a fetched web page, an
+attacker can place instructions where a human viewing the rendered page can
+never see them: inside `<!-- HTML comments -->`, behind `display:none` /
+`visibility:hidden` / `opacity:0` / off-screen / zero-size / clipped / white-on-
+white inline styles, or under the `hidden` / `aria-hidden` attributes. The model
+reading raw source sees them all. Layer 2 splices out exactly those byte ranges
+and leaves a placeholder, **preserving every other byte verbatim**—no
+re-serialization, so links, code, and tables are never reflowed. Scripting and
+resource tags (`<script>`, `<style>`, `<iframe>`, `<svg>`, …) and `data:` URI
+resources are _reported but never removed_, so page source stays inspectable.
+
+**Exfil URLs.** A page can try to make the model leak data by getting it to emit
+or follow a URL shaped to carry a payload off-origin: a credential or blob in a
+query/fragment parameter or path segment, an oversized or active-content `data:`
+URI, embedded `user:password@host` credentials, an off-origin form action or
+`meta refresh` redirect, or a `javascript:` target. Layer 3 **detects and
+reports** these (with a reason and the destination host) without modifying the
+text—enforcement stays with your egress controls; this layer is the warning.
+
+See [THREAT-MODEL.md](./THREAT-MODEL.md) for the per-vector detail.
+
+## Install
+
+```sh
+npm install agent-input-sanitizer
+```
+
+Node ≥ 20. ESM only.
+
+## Usage
+
+### 1. The convenience function
+
+```js
+import { sanitize } from "agent-input-sanitizer";
+
+// Layer 1 only (invisible chars + ANSI), always synchronous work, no heavy deps:
+const { cleaned, found, warnings } = await sanitize(untrustedText);
+
+// Opt into the HTML layers (Layers 2 & 3) for web/HTML ingress:
+const result = await sanitize(fetchedPageSource, { html: true });
+//   result.cleaned   — hidden HTML spliced out, placeholders left in place
+//   result.found     — categories neutralized (e.g. ["Format chars (Cf)", "hidden HTML"])
+//   result.warnings  — human-facing notices (long-run alerts, exfil reasons, …)
+```
+
+`sanitize` never throws and never silently drops content: any change to the text
+is accompanied by at least one entry in `warnings`.
+
+### 2. Just the zero-dependency invisible-char core
+
+```js
+import {
+  stripInvisible,
+  stripInvisibleWithReport,
+} from "agent-input-sanitizer/invisible";
+
+stripInvisible(text); // -> cleaned string
+const { cleaned, found } = stripInvisibleWithReport(text);
+//   found names exactly the categories removed, e.g. ["Variation selectors"]
+```
+
+This entry pulls in **no runtime dependencies**.
+
+### 3. Just the HTML layer
+
+```js
+import {
+  sanitizeHtml,
+  detectExfil,
+  checkExfilUrl,
+} from "agent-input-sanitizer/html";
+
+const layer2 = sanitizeHtml(pageSource); // null when nothing to strip/report
+const threats = detectExfil(pageSource); // null or [{ isImage, reason, target }]
+const reason = checkExfilUrl(oneUrl); // null or a string reason
+```
+
+> **The HTML entry is heavier—import it only when you need it.** It pulls in
+> the unified/remark/rehype graph (~200 ms of module-load time). The convenience
+> `sanitize` lazy-loads it only on the `{ html: true }` path, so a Layer-1-only
+> caller never pays for it. If you import from `agent-input-sanitizer/html`
+> directly, you take that cost at import time.
+
+## Public surface
+
+`agent-input-sanitizer` (main)—`sanitize`, everything re-exported from
+`./invisible`, and the cheap Layer 2/3 pre-gates `HTML_TAG_PRESENT`,
+`MD_LINK_HINT`, `SECRET_HINT`, `SECRET_HINT_EXT`, `matchesSecretHint` (these are
+dependency-free, so re-exporting them never pulls in the heavy HTML graph).
+
+`agent-input-sanitizer/invisible` — `stripInvisible`, `stripInvisibleWithReport`,
+`isSgrOnly`, and the constants `STRIP`, `SGR_RE`, `CHECKS`, `VS`,
+`BLANK_NON_CF`, `LONG_RUN_RE`, `LONG_RUN_THRESHOLD`, `SCATTERED_THRESHOLD`,
+`LINGUISTIC_SCRIPTS`.
+
+`agent-input-sanitizer/html` — `sanitizeHtml`, `scanHtmlFragment`,
+`looksLikeHtmlSource`, `spliceRanges`, `isHiddenStyle`, `isHiddenElement`,
+`isHiddenOpen`, `closingTagName`, `detectExfil`, `checkExfilUrl`, `urlHost`, the
+constants `REPORTED_TAGS`, `COMMENT_PLACEHOLDER`, `HIDDEN_PLACEHOLDER`,
+`DATA_URI_LENGTH_THRESHOLD`, and the pre-gates `HTML_TAG_PRESENT`,
+`MD_LINK_HINT`, `SECRET_HINT`, `SECRET_HINT_EXT`, `matchesSecretHint`.
+
+## Development
+
+```sh
+npm test            # node --test
+npm run coverage    # c8, enforced at 100% lines/branches/functions
+npm run lint        # eslint
+npm run typecheck   # tsc --noEmit (the source is typed via JSDoc)
+```
+
+The test suite is the selling point: 100% coverage is enforced in CI, and the
+enumerated members (each linguistic script, each invisible category, each
+reported tag) are driven from single-source-of-truth lists so adding a member
+without a test fails. Property and fuzz tests (fast-check) exercise idempotence,
+deletion-only output, never-throwing on lone surrogates / astral input, and the
+`found` ⇔ changed invariant over the real Unicode input domain.
+
+## License
+
+[Apache-2.0](./LICENSE)

package/THREAT-MODEL.md

@@ -0,0 +1,77 @@
+# Threat model
+
+`agent-input-sanitizer` defends the boundary where untrusted text enters an
+agent-driven pipeline (agent tool output, RAG retrieval, fetched web pages). It is
+a detect/neutralize layer, not an enforcement boundary: it makes hidden content
+visible-or-gone and surfaces exfil-shaped URLs, so the model and the operator
+see the same thing. Egress controls remain your enforcement layer.
+
+The three layers are independent; use only the ones your ingress needs.
+
+## Layer 1—invisible characters & ANSI (zero-dependency)
+
+**What it removes**
+
+| Category                   | Examples                                                       | Why it’s a payload channel                                    |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
+| Format chars (`Cf`)        | zero-width space/joiner, bidi overrides, Unicode **tag** chars | render blank but reach the model as bytes; tags smuggle ASCII |
+| Variation selectors        | U+FE00–FE0F, U+E0100–E01EF                                     | not `Cf`; a run encodes a hidden payload                      |
+| Blank-rendering fillers    | Hangul fillers U+115F/1160/3164/FFA0, Braille blank U+2800     | render blank, not `Cf`, so a naive `\p{Cf}` strip misses them |
+| Soft hyphen / interior BOM | U+00AD, interior U+FEFF                                        | either can encode hidden instructions                         |
+| ANSI / SGR escapes         | `ESC[…m`, cursor moves, OSC                                    | repaint or hide what an operator reads in a terminal          |
+
+**What it preserves**
+
+- A **single leading BOM** (a legitimate marker); interior BOMs are stripped.
+- **ZWNJ (U+200C) / ZWJ (U+200D)** in genuine linguistic context: between two
+  letters of a script whose orthography requires them (Arabic, Devanagari,
+  Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam,
+  Sinhala) or inside an emoji ZWJ sequence. The carve-out fires only when **both**
+  neighbors clearly belong to the context, and it is disabled once the total
+  invisible count crosses a scatter floor—over-stripping beats under-stripping.
+
+**Reassembly hardening.** Stripping an invisible char can reconstitute an ANSI
+escape its split had hidden, and removing one ANSI sequence can reconstitute
+another. Layer 1 strips ANSI to a fixed point and then sweeps any residual raw
+control introducer—7-bit ESC (U+001B) or 8-bit C1 CSI (U+009B)—outright, so the
+result carries no raw ANSI introducer for _any_ input and the operation is
+idempotent.
+
+## Layer 2—hidden HTML (remark/rehype)
+
+For web/HTML ingress, splice out exactly what a human viewing the rendered page
+cannot see:
+
+- `<!-- HTML comments -->`
+- elements hidden by inline style: `display:none`, `visibility:hidden`,
+  `opacity:0`, off-screen positioning, zero/negative sizes, `text-indent`
+  off-screen, collapsing `clip`/`clip-path`/`transform:scale(0)`, white-on-white
+  / transparent text, `overflow:hidden` with a zero dimension
+- elements hidden by attribute: `hidden`, `aria-hidden="true"`
+
+Spliced ranges are replaced with a placeholder; **every byte outside a spliced
+range is preserved verbatim** (no re-serialization). Unclosed hidden markup
+extends to the end of the fragment—fail-closed for truncated input.
+
+Scripting/resource tags (`script`, `style`, `object`, `embed`, `iframe`, `svg`,
+`math`) and `data:` URI resources are **reported, not removed**: their bodies are
+page source the model may legitimately need to inspect.
+
+## Layer 3—exfil URLs (detection only)
+
+Report—never rewrite—URLs in markdown links/images/definitions and HTML
+attributes (`src`/`href`/`background`/`srcset`/`ping`, form `action`/`formaction`,
+`meta refresh`) that are shaped to carry data off-origin:
+
+- suspicious query/fragment parameters (long base64/hex blobs, credential-shaped
+  tokens), tuned to skip request-signing / pagination / analytics parameters
+  that are legitimately long (`X-Amz-*`, SAS, `cursor`, `utm_*`, `gclid`, …)
+- oversized or active-content (`text/html`, `image/svg+xml`, JS) `data:` URIs
+- embedded `user:password@host` credentials
+- unusually long query strings or fragments
+- encoded-data blobs smuggled in a path segment (a beacon that avoids the query)
+- off-origin form actions and `meta refresh` redirects
+- `javascript:` / `vbscript:` targets
+
+Each threat carries a `reason` and the destination `host` (never the
+payload-bearing query/fragment), suitable for a warning shown to the operator.

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "agent-input-sanitizer",
+  "version": "1.0.0",
+  "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
+  "type": "module",
+  "packageManager": "pnpm@11.8.0",
+  "scripts": {
+    "postinstall": "git config core.hooksPath .hooks",
+    "test": "c8 node --test",
+    "check": "tsc --noEmit",
+    "build:types": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build:types",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "lint-staged": {
+    "*.{css,scss}": [
+      "prettier --write"
+    ],
+    "*.json": [
+      "prettier --write"
+    ],
+    "*.json.example": [
+      "prettier --write --parser json"
+    ],
+    "*.{js,jsx,ts,tsx}": [
+      "prettier --write"
+    ],
+    "*.{yaml,yml}": [
+      "prettier --write"
+    ],
+    "*.md": [
+      "prettier --write"
+    ],
+    ".claude/skills/*/SKILL.md": [
+      ".hooks/lint-skills.sh"
+    ],
+    "{*.sh,.hooks/*}": [
+      "shfmt -i 2 -w"
+    ],
+    "*.py": [
+      "ruff check --fix",
+      "ruff format"
+    ]
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@eslint/js": "10.0.1",
+    "@types/node": "25.9.1",
+    "c8": "11.0.0",
+    "eslint": "10.4.0",
+    "fast-check": "4.8.0",
+    "globals": "17.6.0",
+    "lint-staged": "^17.0.5",
+    "prettier": "^3.0.0",
+    "punctilio": "^3.10.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.61.0"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "llm",
+    "prompt-injection",
+    "sanitize",
+    "unicode",
+    "invisible-characters",
+    "ansi",
+    "exfiltration",
+    "rag",
+    "agent",
+    "security"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./invisible": {
+      "types": "./types/invisible.d.mts",
+      "default": "./src/invisible.mjs"
+    },
+    "./html": {
+      "types": "./types/html.d.mts",
+      "default": "./src/html.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "LICENSE",
+    "README.md",
+    "THREAT-MODEL.md"
+  ],
+  "dependencies": {
+    "rehype-parse": "9.0.1",
+    "remark-gfm": "4.0.1",
+    "remark-parse": "11.0.0",
+    "style-to-object": "1.0.14",
+    "unified": "11.0.5",
+    "unist-util-visit": "5.1.0"
+  }
+}

package/src/gates.mjs

@@ -0,0 +1,54 @@
+/**
+ * Cheap, dependency-free pre-gates shared by the HTML layer (Layers 2 & 3) and
+ * re-exported from both the package root and the `./html` subpath.
+ *
+ * These are pulled out of `html.mjs` so the package root can re-export them
+ * without dragging in the heavy remark/rehype/unified graph: a static
+ * `export … from "./html.mjs"` would eagerly evaluate that ~200ms module on
+ * every root import, defeating the lazy-load design. This module imports
+ * nothing, so re-exporting it is free.
+ */
+
+// ─── Cheap pre-gates ─────────────────────────────────────────────────────────
+
+/**
+ * Matches any HTML tag-like construct: opening tags, closing tags (`</`),
+ * comments (`<!`), and fragments with attributes. Gate for Layer 2 (HTML
+ * sanitization) and the HTML img/a exfil path in Layer 3.
+ */
+export const HTML_TAG_PRESENT = /<[a-zA-Z/!][^<>]*>/;
+
+/**
+ * Matches markdown link/image syntax (`](`, `![`) and reference link
+ * definitions (`[label]: url` at line start). Gate for Layer 3 (markdown
+ * exfiltration detection).
+ */
+export const MD_LINK_HINT = /\]\(|!\[|^[ \t]*\[[^[\]\n]+\]:\s/m;
+
+// ─── Secret-shape pre-gate (Layer 3 URL-param reuse) ─────────────────────────
+// Cheap shape match that decides whether a URL parameter value carries a
+// credential (Layer 3). Split across TWO regexes, combined by matchesSecretHint:
+// one alternation of every arm makes a redos analyzer see cross-arm polynomial
+// backtracking (each arm is linear alone, but the union was a 3rd-degree
+// polynomial on a long alnum run). Testing two independently-safe literals with
+// || is linear and keeps each under the analyzer's bar. The `(?<!...)`
+// lookbehinds on the EXT run-matching arms pin them to a token boundary so they
+// can't be retried at every offset; the atlasv1 arm in SECRET_HINT does the same.
+export const SECRET_HINT =
+  /secret|token|password|passwd|pwd|bearer|credential|authorization|contrase[nñ]a|-----BEGIN|(?:api|auth|service|account|db|database|priv|private|client|access)[_-]?key|(?:db|database|key)[_-]?pass|(?:A3T|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}|gh[pousr]_[A-Za-z0-9]|github_pat_|gl[a-z]{2,12}-[0-9A-Za-z_-]{20}|sk-ant-|AIza[0-9A-Za-z_-]{35}|sk_live_|sk_test_|rk_live_|rk_test_|xox[bpasr]-|eyJ[A-Za-z0-9]|do[opr]_v1_[a-f0-9]{16}|v1\.0-[a-f0-9]{24}-|hv[sb]\.[A-Za-z0-9_-]{20}|(?<![a-z0-9])[a-z0-9]{14}\.atlasv1\.|sk-or-v1-[0-9a-f]{16}|gsk_[A-Za-z0-9]{16}|xai-[A-Za-z0-9]{16}|r8_[A-Za-z0-9]{16}/i;
+
+// Second alternation (see SECRET_HINT): kept a separate literal so a redos
+// analyzer vets each alternation in isolation.
+export const SECRET_HINT_EXT =
+  /(?:AC|SK)[a-z0-9]{32}|SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}|sq0csp-[0-9A-Za-z_-]{43}|(?<![0-9])[0-9]{8,10}:[0-9A-Za-z_-]{35}|(?<![0-9a-z])[0-9a-z]{32}-us[0-9]{1,2}|(?<![A-Za-z0-9_-])[MNO][A-Za-z0-9_-]{23,25}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27}|T3BlbkFJ|pypi-AgE|(?<![A-Za-z0-9])AKC[A-Za-z0-9]{10}|(?<![A-Za-z0-9])AP[0-9A-Fa-f][A-Za-z0-9]{8}|:\/\/[^\s:/@]{1,64}:[^\s:/@]{1,64}@|(?:key|pw|pass)["']?[\s:=>]+["']?[A-Za-z0-9_/+-]{20}/i;
+
+/**
+ * True when either pre-gate alternation shape-matches `text`. Split into two
+ * literals (see SECRET_HINT) and OR'd so neither grows into a
+ * polynomial-backtracking shape.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function matchesSecretHint(text) {
+  return SECRET_HINT.test(text) || SECRET_HINT_EXT.test(text);
+}