nolimit-security-dist/docs/CONTRACT.md

What this plugin offers, and what it asks for

Written from the shipped source, and checked against it in both directions on every release: a hook in the code and not in this file fails the build, and a hook in this file and not in the code fails it too.

Three roles, because they are not the same thing and add_filter is how you answer a filter, not how you consume one:

• Offers — do_action / apply_filters on a nlsec_ name. Yours to hook.
• Answers — add_filter on a name a consumer applies. We supply the value.
• Asks — apply_filters on a wpmgr_ name. Somebody else supplies it.

---

Offers — ten hooks on our own prefix

Hook	Kind	Fires when	Notes for a consumer
nlsec_request_blocked	action	Just before a request is refused	The only place a refusal is observable. It fires only when somebody is being refused, so anything here runs on the path a real visitor is stuck on.
nlsec_finding_recorded	action	A scanner or vulnerability finding is written	Carries a machine-readable code. Match on that, never on the title — a rule matching a title dies the day anybody translates one.
nlsec_scan_complete	action	A scan finishes	Fires on a clean scan too. "No findings" and "never ran" are different states.
nlsec_privileged_login	action	An administrator signs in
nlsec_recovery_code_used	action	A two-factor recovery code is spent	Worth alerting on. A spent recovery code means somebody lost their second factor, or somebody else found it.
nlsec_ai_briefing	action	The analyst produces a briefing
nlsec_ai_acted	action	The analyst acts on its own proposal
nlsec_firewall_rules	filter	Rules are assembled	Add or remove rules.
nlsec_malware_signatures	filter	Signatures are assembled	A pattern that does not compile is reported by NLSEC_Signatures::broken(), not turned into a warning on every file.
nlsec_public_rest_routes	filter	REST lockdown decides what stays public	Read this one if you ship REST routes. When hardening locks the REST API down, only the prefixes in this list stay reachable to a logged-out visitor. Defaults include /wc/store, /contact-form-7, /wpcf7. A plugin whose routes a shop's front end needs should add its prefix here rather than ask the owner to switch the lockdown off. Off by default, because most modern themes use REST from the front end.
nlsec_request_reputation	filter	—	Defined here, answered here, applied by the consumer. See below.

Answers — four

Hook	Who applies it	What we return
nlsec_request_reputation	Any plugin that wants a verdict on a submitter	An array, or the caller's null untouched if we are absent.
wpmgr_dashboard_cards	shared-menu.php	Our dashboard card.
wpmgr_signals	Nolimit Assistant, and nothing else	Our signals.
wpmgr_setup_recommendations	Nolimit Assistant, and nothing else	Three hardening switches for its Setup screen: hide the WordPress version and turn off pingbacks (both safe, both with an undo), and browser security headers (confirm). Each done is read from the stored setting, each apply returns true or a WP_Error, and none offers a number or a secret. We answer it and never apply it.

wpmgr_signals is collected by Nolimit Assistant alone. With that plugin deactivated our signals go to a filter nobody applies, and nothing raises an error — the answering side of a filter cannot tell whether anyone ever collected it. A collector has to live somewhere; anyone reading a family-wide signal list is reading Assistant's.

nlsec_request_reputation in full

$verdict = apply_filters( 'nlsec_request_reputation', null, $ip );

$ip is optional and defaults to the current request. null back means nobody answered — read it as "nothing is known", never as "clean". The consumer keeps its own fallback and carries no hard dependency on us.

Returns:

Field
suspicious	bool
exempt	bool — the address is on the site owner's allowlist
reason	a sentence for a human
code	blocked-now, on-threat-list, blocked-recently, near-rate-limit, allowlisted, or ''
severity	0–5
measured	which of allowlist, blocks, lists, log, rate actually answered
ip	the address judged

Severity is pinned and asserted by the plugin's own tests, because a consumer branches on the number: blocked-now 5, on-threat-list 4, blocked-recently 2–4, near-rate-limit 2, allowlisted 0. Moving one is a red test that names who to tell.

measured is the field to wire in. "Nothing known about this address" and "I could not look" are both zeros; measured is how a caller tells them apart. If log is missing our log table was unreadable, and a clean verdict from four sources is not the same claim as one from five.

exempt is stated, not implied. suspicious => false is what a clean stranger gets too. An allowlisted address must never be refused through us, because we do not refuse it ourselves: run_main() checks the allowlist before the block list, so an allowlisted address carrying a stale block row is waved past by our own firewall.

What a consumer must not do:

• Do not treat null as clean.
• Do not act on severity without also handling exempt.
• Do not check the current user's capability through us — this filter takes an arbitrary address, which need not be the requester's, so "is this a logged-in administrator" is a question only the caller can answer.
• Do not both answer and apply this filter. A provider that also reads the filter it answers builds an infinite mutual recursion, invisible in either file because each half is three obvious lines. The only apply_filters( 'nlsec_request_reputation' ) in our shipped tree is inside the docblock above it.

wpmgr_dashboard_cards is answered and applied in this tree, and that is safe only because the two are in different files doing different jobs: class-plugin.php adds our card, shared-menu.php collects everybody's. Our callback does not re-apply. That is the line; it is one edit away from being crossed.

Emits to the family — one

Hook	Kind	Who listens	What it carries
wpmgr_ai_usage	action	Nolimit Assistant	( 'nolimit-security', array( 'provider', 'model', 'input', 'output', 'purpose' ) ) — what this plugin spent on an AI call.

The point of it is that one plugin can show one honest total rather than four partial ones. It is a wpmgr_ name we emit rather than ask for.

Asks — four

Hook	Who answers	What we do when nobody does
wpmgr_ai_credentials	Nolimit Assistant	The analyst stays off. No error, no nag.
wpmgr_dashboard_cards	Every family plugin	Draw the cards we got.
wpmgr_menu_title	Any family plugin	Fall back to the built-in title.
wpmgr_menu_glyph	Any family plugin	Fall back to the built-in glyph.

The card contract

The shared menu reads exactly title, colour, status, headline, lines, url and action from a card. Four mistakes are easy to make:

• href instead of url — the card draws, the button goes nowhere
• no colour — falls back to a neutral grey
• lines as a numeric list instead of label => value — values with no labels
• name instead of title — a card without a title is skipped, so the whole card disappears, silently. The only one of the four that renders as absence.

WordPress core hooks we use as an interface

plugins_api — guarded on $args->slug. rest_api_init — registers nlsec/v1. Listed so a core hook can be told from an undocumented one of ours. The update filter update_plugins_{$host} is shared by every plugin that updates from the same host, so ours answers only for itself.

Internal only — not a contract

nlsec_hourly_event, nlsec_scan_event, nlsec_ai_briefing_event, nlsec_ai_triage_event, nlsec_digest_event, nlsec_surge_check are our own scheduled hooks. Nothing outside this plugin should hook them and they may be renamed without notice.