OAuth connections and plugin-registered skills (0.4.0)

README.md

@@ -10,9 +10,9 @@ Site Agent is free and open source. The complete release ZIP and a free automati
 
 ## Companion Package
 
-Release 0.3.0 also includes `site-agent-companion-0.3.0.zip`, built from `companion/site-agent/`. It supplies the approved icon, a credential-free MCP connection and a WordPress workflow skill for compatible ChatGPT/Codex hosts. The skill covers site inspection, raw-content audits, draft preparation, hash-checked edits and enabled developer tools.
+Release 0.4.0 also includes `site-agent-companion-0.4.0.zip`, built from `companion/site-agent/`. It supplies the approved icon, a credential-free MCP connection and a WordPress workflow skill for compatible ChatGPT/Codex hosts. The skill covers site inspection, raw-content audits, draft preparation, hash-checked edits and enabled developer tools.
 
-This companion archive is separate from the WordPress installable ZIP. Authentication must be configured privately through a compatible host. It does not implement OAuth or establish authenticated ChatGPT web connectivity. The server requires a WordPress Application Password through a Basic Authorization header or explicitly enabled URL authentication. OAuth remains unimplemented, and ChatGPT web compatibility with credential-bearing URLs has not been verified.
+This companion archive is separate from the WordPress installable ZIP and contains no credentials. With OAuth connections on (0.4.0+), an OAuth-capable host signs in through WordPress and needs nothing else. Otherwise, authentication is configured privately through the host with a WordPress Application Password in a Basic Authorization header or an explicitly enabled authenticated URL. ChatGPT web compatibility with credential-bearing URLs has not been verified.
 
 Build and validate the companion with `python3 bin/build-companion.py`. Never include credentials in its manifests or archive.
 
@@ -124,7 +124,32 @@ License activation explicitly sends the key, site URL, plugin version, WordPress
 
 Update metadata is cached for three hours and partitioned by site, credentials and plugin version. A fresh protected URL is fetched before both single and bulk downloads. Packages require HTTPS on the store or its FluentCart R2 host, and their extracted name/version must match the offered Site Agent release. Invalid licenses never receive a package, and older versions are not offered as updates. Manual release ZIP updates remain available. See [Security and Access](#security-and-access) for the trust model.
 
-OAuth, background WP-CLI jobs, an AI chat UI and a recoverable PHP sandbox are outside this version.
+Background WP-CLI jobs, an AI chat UI and a recoverable PHP sandbox are outside this version.
+
+## OAuth connections
+
+Version 0.4.0 adds opt-in OAuth 2.1 following the MCP authorization specification. Turn on **OAuth connections** in Tools → Site Agent, then add the endpoint to an OAuth-capable client with no credentials:
+
+- An unauthenticated MCP request answers 401 with `WWW-Authenticate: Bearer resource_metadata="…/wp-json/site-agent/v1/oauth/protected-resource"`.
+- Protected resource metadata (RFC 9728) and authorization server metadata (RFC 8414) are served through REST and at the path-inserted well-known URLs, `/.well-known/oauth-protected-resource/wp-json/site-agent/v1/mcp` and `/.well-known/oauth-authorization-server/wp-json/site-agent/v1/oauth`, plus the OpenID Connect forms, including `/wp-json/site-agent/v1/oauth/.well-known/openid-configuration`. The issuer is `…/wp-json/site-agent/v1/oauth`, so Site Agent never takes over the site-root discovery documents that another plugin's OAuth server may serve (Rank Math's MCP server does).
+- Clients register through RFC 7591 dynamic client registration as public clients. Redirect URIs must use HTTPS, an HTTP loopback address, or a private-use scheme.
+- The authorization endpoint is a consent screen in wp-admin. An administrator signs in, sees the client and its return address, picks which enabled tool groups it may use, and allows or denies it. PKCE with S256 is required, codes are single-use and last ten minutes, and the response carries `iss` (RFC 9207).
+- Access tokens last one hour and refresh tokens rotate, ending after 30 days without use. Only HMAC hashes are stored, in the approving user's meta. Tokens authenticate only the MCP route. Reusing a rotated refresh token ends the connection. Tokens stop working when OAuth is turned off, Site Agent is disabled, or the approving account loses administrator rights.
+- Approved groups narrow access like per-password limits; Site Agent's switches and wp-config.php constants still apply. Audit history shows `via: oauth` and the client name.
+- Revoke a connection in Tools → Site Agent or through the RFC 7009 revocation endpoint. Uninstalling always removes OAuth clients and connections.
+
+## Skills from other plugins
+
+Plugins can add read-only skills to `list-skills` and `get-skill` with the `site_agent_skills` filter:
+
+```php
+add_filter( 'site_agent_skills', function ( $skills ) {
+	$skills['my-plugin-workflow'] = array( 'directory' => __DIR__ . '/skills/workflow', 'plugin' => 'My Plugin', 'version' => '1.2.0' );
+	return $skills;
+} );
+```
+
+Names use lowercase letters, numbers and hyphens, and cannot replace the bundled builder skills. The directory must contain `SKILL.md`. Only Markdown, JSON and HTML files up to 64 KiB are served, through the same path checks as bundled skills. At most 20 registered skills are listed.
 
 ## Security and Access
 
@@ -142,7 +167,7 @@ python3 bin/sync-skills.py
 bash bin/build.sh
 ```
 
-Tests refuse to load an installation without a `.site-agent-test-install` marker. Never place that marker on a real site. Integration tests modify disposable options, users, posts, and fixture files. The build uses a runtime allowlist and excludes tests, development dependencies, Composer metadata, docs, and screenshots. Ship `dist/site-agent-0.3.0.zip`, not a GitHub source archive.
+Tests refuse to load an installation without a `.site-agent-test-install` marker. Never place that marker on a real site. Integration tests modify disposable options, users, posts, and fixture files. The build uses a runtime allowlist and excludes tests, development dependencies, Composer metadata, docs, and screenshots. Ship `dist/site-agent-0.4.0.zip`, not a GitHub source archive.
 
 ## License and Contributions
 

companion/site-agent/.codex-plugin/plugin.json

@@ -2,7 +2,7 @@
   "interface": {
     "displayName": "Site Agent",
     "shortDescription": "WordPress content and code",
-    "longDescription": "Site Agent helps WordPress site owners, editors, and developers work with their site's content and code from ChatGPT.\n\nInspect WordPress and PHP versions, installed plugins, the active theme, and enabled tools. Find posts, pages, and media; audit raw content; prepare drafts; and apply scoped edits while preserving Gutenberg markup, ACF data, shortcodes, links, and placeholders. Content updates use the latest content hash to detect intervening changes.\n\nFor developer tasks, separately enabled tools can inspect plugin and theme files, make hash-checked source edits, execute PHP, and run foreground WP-CLI commands. Developer tools run with server privileges and are not sandboxed.\n\nRequires the Site Agent WordPress plugin, an enabled MCP endpoint, and a compatible authenticated connection using a dedicated WordPress Application Password. Authentication is configured separately; credentials are not included. Available features depend on the tool groups enabled on your site. Basic Authorization header compatibility with the ChatGPT host has not been verified.\n\nSite Agent is free and open source. Learn more at https://gauravtiwari.org/product/site-agent/.",
+    "longDescription": "Site Agent helps WordPress site owners, editors, and developers work with their site's content and code from ChatGPT.\n\nInspect WordPress and PHP versions, installed plugins, the active theme, and enabled tools. Find posts, pages, and media; audit raw content; prepare drafts; and apply scoped edits while preserving Gutenberg markup, ACF data, shortcodes, links, and placeholders. Content updates use the latest content hash to detect intervening changes.\n\nFor developer tasks, separately enabled tools can inspect plugin and theme files, make hash-checked source edits, execute PHP, and run foreground WP-CLI commands. Developer tools run with server privileges and are not sandboxed.\n\nRequires the Site Agent WordPress plugin and an enabled MCP endpoint. With OAuth connections on (Site Agent 0.4.0+), the host signs in through WordPress and an administrator approves it; otherwise use a dedicated WordPress Application Password configured privately in the host. Credentials are not included. Available features depend on the tool groups enabled on your site. Basic Authorization header compatibility with the ChatGPT host has not been verified.\n\nSite Agent is free and open source. Learn more at https://gauravtiwari.org/product/site-agent/.",
     "developerName": "Gaurav Tiwari",
     "category": "Productivity",
     "logo": "./assets/icon.png",
@@ -19,7 +19,7 @@
     "termsOfServiceURL": "https://gauravtiwari.org/tos/"
   },
   "name": "site-agent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A WordPress assistant for site inspection, content audits, draft creation, and hash-checked edits through Site Agent's MCP tools.",
   "author": {
     "name": "Gaurav Tiwari",

companion/site-agent/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "site-agent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A WordPress assistant for site inspection, content audits, draft creation, and hash-checked edits through Site Agent's MCP tools.",
   "author": {
     "name": "Gaurav Tiwari",
@@ -12,7 +12,7 @@
       "interface": {
         "displayName": "Site Agent",
         "shortDescription": "WordPress content and code",
-        "longDescription": "Site Agent helps WordPress site owners, editors, and developers work with their site's content and code from ChatGPT.\n\nInspect WordPress and PHP versions, installed plugins, the active theme, and enabled tools. Find posts, pages, and media; audit raw content; prepare drafts; and apply scoped edits while preserving Gutenberg markup, ACF data, shortcodes, links, and placeholders. Content updates use the latest content hash to detect intervening changes.\n\nFor developer tasks, separately enabled tools can inspect plugin and theme files, make hash-checked source edits, execute PHP, and run foreground WP-CLI commands. Developer tools run with server privileges and are not sandboxed.\n\nRequires the Site Agent WordPress plugin, an enabled MCP endpoint, and a compatible authenticated connection using a dedicated WordPress Application Password. Authentication is configured separately; credentials are not included. Available features depend on the tool groups enabled on your site. Basic Authorization header compatibility with the ChatGPT host has not been verified.\n\nSite Agent is free and open source. Learn more at https://gauravtiwari.org/product/site-agent/.",
+        "longDescription": "Site Agent helps WordPress site owners, editors, and developers work with their site's content and code from ChatGPT.\n\nInspect WordPress and PHP versions, installed plugins, the active theme, and enabled tools. Find posts, pages, and media; audit raw content; prepare drafts; and apply scoped edits while preserving Gutenberg markup, ACF data, shortcodes, links, and placeholders. Content updates use the latest content hash to detect intervening changes.\n\nFor developer tasks, separately enabled tools can inspect plugin and theme files, make hash-checked source edits, execute PHP, and run foreground WP-CLI commands. Developer tools run with server privileges and are not sandboxed.\n\nRequires the Site Agent WordPress plugin and an enabled MCP endpoint. With OAuth connections on (Site Agent 0.4.0+), the host signs in through WordPress and an administrator approves it; otherwise use a dedicated WordPress Application Password configured privately in the host. Credentials are not included. Available features depend on the tool groups enabled on your site. Basic Authorization header compatibility with the ChatGPT host has not been verified.\n\nSite Agent is free and open source. Learn more at https://gauravtiwari.org/product/site-agent/.",
         "developerName": "Gaurav Tiwari",
         "category": "Productivity",
         "logo": "./assets/icon.png",

companion/site-agent/skills/wordpress-assistant/references/connection.md

@@ -2,14 +2,14 @@
 
 Endpoint supplied by the owner: https://gauravtiwari.org/wp-json/site-agent/v1/mcp
 Transport: Streamable HTTP.
-Server source requires HTTPS and native WordPress Application Password authentication, supplied through a Basic Authorization header or explicitly enabled URL authentication. The supplied Authorization value was a placeholder, not a usable credential. OAuth is outside the server's current version.
+Server source requires HTTPS. It accepts OAuth 2.1 bearer tokens when the site turns on OAuth connections (Site Agent 0.4.0+), and native WordPress Application Passwords through a Basic Authorization header or explicitly enabled URL authentication. The supplied Authorization value was a placeholder, not a usable credential.
 
-This package deliberately contains no Authorization header or credentials. Use a host-supported private connection setting to supply authentication if the host supports this server's Basic header requirement. If the host requires OAuth, or cannot configure headers or retain an authenticated URL, the direct connection is blocked; report that limitation. Do not claim installation authenticates the server, invent an OAuth endpoint, publish credentials in a manifest, or silently deploy a proxy.
+This package deliberately contains no Authorization header or credentials. Use a host-supported private connection setting to supply authentication if the host supports this server's Basic header requirement. If the host requires OAuth, the site owner turns on OAuth connections in Tools > Site Agent; the host then discovers the sign-in page from the endpoint's 401 response and the administrator approves it on a WordPress consent screen. If OAuth is off and the host cannot configure headers or retain an authenticated URL, the direct connection is blocked; report that limitation. Do not claim installation authenticates the server, invent an OAuth endpoint, publish credentials in a manifest, or silently deploy a proxy.
 
 WordPress setup: install the complete Site Agent release ZIP, open Tools > Site Agent, enable access and required groups, and create a dedicated Application Password in the administrator's profile. On multisite, server access requires super-administrator rights. Keep developer groups off unless the task needs them.
 
 Never ask for credentials in chat. The Tools > Site Agent converter runs in the browser and can generate a Basic header for a compatible client. Use secure host credential entry when available. Disabling Site Agent or revoking the dedicated Application Password revokes access.
 
 Verification after connection: discover live tools, call the harmless site-context tool, verify site_url and enabled_tools, then read existing content. Do not test authentication with a write.
 
-The server also supports explicitly enabled URL authentication via an auth query parameter containing Base64-encoded username and Application Password credentials. Keep the complete URL only in a host-supported private connection setting, never in manifests, instructions or reports. Each request must retain its query parameters. OAuth-only hosts or clients that discard the query still require a compatible bridge; do not claim universal client support.
+The server also supports explicitly enabled URL authentication via an auth query parameter containing Base64-encoded username and Application Password credentials. Keep the complete URL only in a host-supported private connection setting, never in manifests, instructions or reports. Each request must retain its query parameters. OAuth-only hosts should use OAuth connections instead; clients that discard the query and lack OAuth are not supported. Do not claim universal client support.

companion/site-agent/skills/wordpress-assistant/references/tools.md

@@ -9,8 +9,8 @@ Reference source: wpgaurav/site-agent 0.3.0, includes/class-abilities.php, inclu
 | site-agent-get-content | post_id, url or slug (+ post_type), autosave_content | Raw content, title, slug, status, dates, link, terms, featured_media, meta, your autosave (newer flag; its text with autosave_content), builder, content_sha256 |
 | site-agent-list-terms | taxonomy, search, limit, page | Term IDs, names, slugs, parents and counts; default category, 50 results |
 | site-agent-list-media | mime_type, search, limit, page | Existing media IDs, URLs, MIME types, dimensions and alt text |
-| site-agent-list-skills | none | Bundled builder skills (gutenberg, generateblocks, elementor, bricks, divi), whether each builder is active, and their files |
-| site-agent-get-skill | skill required; path (default SKILL.md) | Read a builder skill or one of its reference, pattern or example files |
+| site-agent-list-skills | none | Bundled builder skills (gutenberg, generateblocks, elementor, bricks, divi) and skills active plugins add (for example gtfc-invoice), whether each applies here, source plugin and files |
+| site-agent-get-skill | skill required; path (default SKILL.md) | Read a builder or plugin skill, or one of its reference, pattern or example files |
 | site-agent-save-content | post_id, post_type, title, content, excerpt, status, slug, date_gmt, terms, featured_media, meta, expected_content_sha256 | Creates default to draft; updates require current hash; edits to live posts are staged unless status is passed |
 | site-agent-upload-media | url or data_base64 + filename; title, alt, caption, description, post_id | Import into the media library with alt text |
 | site-agent-update-media | id required; title, alt, caption, description | Change media metadata |