@tunnelmindai/checks

Part of TunnelMind — the intelligence layer agents call before they trust the internet. Three lenses on one signed corpus: Scry (who is attacking?) · Sigil (who can you trust?) · Tracker Data API (who is watching?). This repo serves: the open protocol layer alongside ATAP and OAI. Currently powers Sigil's verification surface; designed to be reusable by anyone. Apache-2.0. See tunnelmind.ai.

Pure, deterministic checks for the agentic internet. Text in, structured data out. No network. No I/O. No config. No DB. No secrets.

Powers the verification surface behind Sigil and sits alongside ATAP and the OAI standard in the open TunnelMind protocol layer.

What's in the box

| Module | Export | What it does | |---|---|---| | @tunnelmindai/checks/ads-txt | parseAdsTxt(raw) | Parse an IAB ads.txt v1.1 (July 2022) file. Returns entries + directives + malformed counts. Handles BOM, inline comments, the five v1.1 variables (CONTACT, SUBDOMAIN, OWNERDOMAIN, MANAGERDOMAIN with country, INVENTORYPARTNERDOMAIN), semicolon extension fields, mixed line endings, case-insensitive type field. | | @tunnelmindai/checks/ads-txt | diffAdsTxt(prevEntries, prevDirectives, nextEntries, nextDirectives) | Compute the change-set between two parsed ads.txt snapshots. | | @tunnelmindai/checks/sellers-json | parseSellersJson(obj) | Parse an IAB OpenRTB sellers.json v1.0 object (post-JSON.parse). Lenient — accepts wire-mess that real publishers ship; counts what it skips. Returns { contact_email, version, identifiers, sellers, intermediary_domains, … }. | | @tunnelmindai/checks/sellers-json | classifySellerId(id) | Heuristic on a seller_id string: uuid | numeric | alphanumeric | domain-like | unknown. | | @tunnelmindai/checks/psl | registrableDomain(host) | Public Suffix List-accurate registrable-domain resolution. registrableDomain("healthination.cnn.com") === "cnn.com". Returns null when the host IS itself a public suffix. | | @tunnelmindai/checks/psl | sameRegistrableDomain(a, b) | True when two hostnames share the same registrable (root) domain. |

The PSL data is vendored from https://publicsuffix.org/list/ (Mozilla Public License 2.0; the embedded list is treated as data, not code, and is updated by re-vendoring).

Install

npm install @tunnelmindai/checks

Node 20+. Zero runtime dependencies.

Use

import { parseAdsTxt, parseSellersJson, registrableDomain } from '@tunnelmindai/checks'

const ads = parseAdsTxt(`
# nytimes.com ads.txt
google.com, pub-1234, DIRECT, f08c47fec0942fa0
pubmatic.com, 156025, RESELLER, 5d62403b186f2ace
MANAGERDOMAIN=adops.nytimes.com, US
[email protected]
`)
// → { entries: [...], directives: { manager_domains: [{domain, country}], contact, ... }, ... }

const sellers = parseSellersJson(JSON.parse(rawSellersJsonText))
// → { contact_email, version, sellers: [...], identifiers: [...], intermediary_domains: [...] }

registrableDomain("ads.healthination.cnn.com")  // "cnn.com"
registrableDomain("co.uk")                       // null (host is a public suffix)

Or import per-domain:

import { parseAdsTxt } from '@tunnelmindai/checks/ads-txt'
import { registrableDomain } from '@tunnelmindai/checks/psl'

Why pure

Every function in this package is a pure function: the same input always produces the same output, and the function has no side effects.

That property is the whole point. The Sigil verification API uses these checks behind a network surface and a cache; a downstream agent that wants to reproduce a Sigil verdict locally can run the same checks with the same inputs and get the same answer. The data is what's scarce — the algorithms are open.

License

Apache-2.0.