Skip to content

Architecture

xNetVN Development edited this page Nov 12, 2026 · 2 revisions

Architecture

This page traces one MCP request through the plugin, then describes the layer boundaries and where data lives. It summarizes docs/en/architecture/overview.md, docs/en/architecture/persistence.md and the source under src/.

Product identity

Item Value Source
PHP namespace / PSR-4 root XNetVN\AgentHubWP / src/ composer.json, docs/en/architecture/overview.md
Plugin slug, text domain, server ID xnetvn-agent-hub-wp xnetvn-agent-hub-wp.php, src/Mcp/ServerGateway.php
Ability namespace xnetvn/ docs/en/architecture/overview.md
Function, hook and option prefix xnetvn_agent_hub_wp_ docs/en/architecture/overview.md
MCP route /xnetvn-agent-hub-wp/mcp src/Http/RouteMatcher.php
Management route namespace xnetvn-agent-hub-wp/v1 src/Rest/ManagementGate.php

Request path, end to end

Client (bearer key)
   │  HTTPS  POST /wp-json/xnetvn-agent-hub-wp/mcp
   ▼
[1] RouteMatcher ── exact, normalized route only
   ▼
[2] OriginGuard / TransportGuard ── deny before auth
   ▼
[3] Authenticator ── bearer key → AuthContext (never cookie identity)
   ▼
[4] Policy + scope recheck ── capability ∩ key ∩ site ∩ toolset
   ▼
[5] ServerGateway ── the only adapter-aware class
   ▼
[6] Registry ── private ability definition, rechecked at invoke
   ▼
[7] OutputPipeline ── validate, redact, bound, revalidate
   ▼
[8] AuditLogger ── one bounded INSERT at shutdown (names only)
  1. Exact route matching. RouteMatcher::matches() accepts only a real REST request whose normalized route equals /xnetvn-agent-hub-wp/mcp after trimming trailing slashes. No namespace-prefix match is allowed, so a neighbouring route never inherits bearer authentication (src/Http/RouteMatcher.php).
  2. Guards before authentication. Origin and TLS checks run at REST authentication priority 5 and deny unsafe requests before any credential is read. A missing Origin is permitted for non-browser clients; an explicit null or an unlisted origin is denied (docs/en/architecture/overview.md).
  3. Authentication. Authenticator reads only the credential header, verifies the HMAC-SHA256 secret against the per-site pepper, then rechecks revocation, expiry, owner existence, the owner's current use_xnetvn_agent_hub_wp capability, key and site IP allowlists, site enablement and TLS. Only then does it create a request-local AuthContext and charge the per-key budget. A cached cookie user is reauthenticated at REST priority 80; a prior cookie identity never substitutes for a key (src/Auth/Authenticator.php).
  4. Policy. Policy::evaluate() returns the first failing term: transport/identity, site enabled, site tier ceiling, admin-tier opt-in, key tier, toolset, explicit allow/deny, third-party approval, then the live WordPress capability for the ability's visibility capability, then an extension filter that may only deny (src/Policy/Policy.php).
  5. Gateway. ServerGateway registers five adapter hooks and filters the advertised tool list to the names the presented scope can use, but only on the exact MCP route (src/Mcp/ServerGateway.php).
  6. Registry. Registry is the authority for ability metadata. It rejects duplicate ability or tool identities, loads packs on init priority 0, and registers categories and abilities through the WordPress Abilities API. allowed() rechecks the bound ability object and current policy; invoke() rechecks again, applies the per-key expensive-work budget, then runs the output pipeline (src/Abilities/Registry.php).
  7. Output. OutputPipeline::process() validates against the declared schema, removes sensitive property names recursively, validates again, enforces output_max_bytes (default 262144), and truncates only when the schema declares a truncated property. If no valid bounded result exists, the tool fails with a safe execution error instead of returning invalid structured content (src/Abilities/OutputPipeline.php).
  8. Audit. AuditLogger buffers metadata and writes one bounded INSERT at shutdown. It stores time, request ID, key ID, user ID, transport, protocol version, MCP method, ability, outcome, error code, duration, IP, short user agent and top-level argument names — never argument values, credentials, headers or hashes (src/Audit/AuditLogger.php, docs/en/adr/0010-minimal-audit.md).

The adapter boundary

Only src/Mcp/ServerGateway.php references adapter symbols (mcp_adapter_*, WP_MCP_VERSION); a repository-wide search of src/ returns that file alone. Packs, policy, authentication, persistence, REST and admin code never import adapter APIs, so an adapter upgrade is contained in one facade (docs/en/architecture/adapter-notes.md, docs/en/specs/M1-core.md).

Ability registration declares no public or show_in_rest metadata: abilities stay private, and core may inject show_in_rest=false, which must remain false. Unsupported adapter versions leave the plugin loadable while MCP boot stays closed (src/Bootstrap/Requirements.php).

Bootstrap and service-provider layering

The entry file uses PHP 7.2-compatible syntax only, loads Requirements, Notice and Loader, and calls Loader::run(). The loader fails closed: if PHP, WordPress, the Abilities API or vendor/autoload.php is missing, it registers an admin notice and never loads modern code. Otherwise it boots Plugin, which registers an ordered list of ServiceProvider implementations once and dispatches xnetvn_agent_hub_wp_loaded (xnetvn-agent-hub-wp.php, src/Bootstrap/Loader.php, src/Plugin.php).

Layer Responsibility Examples
Admin / REST / CLI Input handling and UI src/Admin/Pages.php, src/Rest/*Controller.php
Services Orchestration and rules KeyService, Registry, Policy
Domain Pure value objects, no WordPress calls RiskTier, Scope, AuthContext
Persistence / rate limit Contract implementations WpdbKeyRepository, WpBucketStore
Packs Ability definitions and handlers src/Abilities/Packs/*

Where data lives

Store Name Purpose
Table {prefix}xnetvn_agent_hub_wp_keys Key metadata, HMAC hash, pepper ID, scope, usage, revocation
Table {prefix}xnetvn_agent_hub_wp_audit Audit rows, indexed by time, key, user and ability
Option xnetvn_agent_hub_wp_settings Validated, non-autoloaded site policy
Option xnetvn_agent_hub_wp_pepper Separate random pepper, non-autoloaded
Option xnetvn_agent_hub_wp_db_version Forward-only schema version
Options Rate buckets Non-autoloaded counters when no persistent object cache exists

Both tables are created per site by Schema::statements(); the schema version is forward-only and a future version is refused (src/Persistence/Schema.php, docs/en/architecture/persistence.md). See Operations for backup implications and Security-Model for the trust boundaries.

Extension surface

xnetvn_agent_hub_wp_loaded hands the registered kernel to extensions. Deny-only filters (..._taxonomy_allowed, ..._user_allowed), add-only filters (..._user_privileged_caps, ..._user_meta_writable) and the extra policy filter preserve the base intersection and can never widen it. Tier filters may only raise risk (docs/en/architecture/overview.md).

Nothing here proves runtime acceptance. Implemented primitives and measured acceptance are recorded separately in docs/en/TESTING.md; see Testing.

Clone this wiki locally