=== PropertyRightsWeb™ ===
Contributors: personaldigitalspaces
Tags: rsl, licensing, ai, crawlers, monetization
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 0.4.3
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

License your WordPress content to AI companies: set your terms, publish them in a machine-readable standard, and get paid when your work is used.

== Description ==

AI systems train on and retrieve web content every day, usually without permission or payment. PropertyRightsWeb™ lets you take control: decide what AI is allowed to do with your content, publish those terms in a way AI crawlers can read, and collect a fee when they use your work.

You organize your content into **asset bundles**: groups of URLs that share one price and one set of permitted and prohibited uses. The plugin publishes those terms so AI companies can buy the appropriate license before using your work.

Licensing is not limited to AI training. Your terms cover the full range of AI uses (training, retrieval/RAG, and more) through the permits and prohibits you set on each offer.

= What you need to get started =

You can install the plugin by itself to scan your WordPress site and organize its content into bundles. This gives you a local catalog of the content you may want to license.

To publish licensing terms, sell licenses, and receive payment, you must also connect:

1. **A PDS account**: provides your marketplace identity and wallet. See Installation below.
2. **A validator service**: allows AI companies to obtain and pay for a license before using your content. You or a service provider operates it.

These are separate external services. Installing or activating the WordPress plugin does **not** install, start, or host them. You must set them up and connect them to the plugin.

= Learn more =

* OpenRSL, the open standard this plugin implements: https://openrsl.org
* Publisher guide: https://openrsl.org/publishers
* Developer guide: https://openrsl.org/developers

**Not affiliated with the RSL Collective.** PropertyRightsWeb™ implements RSL (Really Simple Licensing), an open standard for publishing machine-readable content licensing terms. The names "RSL" and "Really Simple Licensing" appear here only to identify that standard. This plugin and its author, Personal Digital Spaces, are independent of the RSL Collective and are not affiliated with, sponsored by, or endorsed by it.

== External Services ==

This plugin relies on the following external services to register assets, sell licenses, settle payments, and (optionally) report client-side diagnostics. Each entry lists what the service does, what data is sent, and when.

**Whose terms apply.** Every endpoint below is operator-configured. If you use the hosted PropertyRightsWeb™ service, the Terms of Service and Privacy Policy linked in each entry (https://propertyrightsrsl.app) govern your use of it. If you self-host any of these services, or point the plugin at a third-party operator, that operator sets the terms for their instance and the links below do not govern it; the plugin sends data only to the endpoints you configure.

1. **PDS (Personal Digital Spaces)**: the marketplace and asset registry.
   * What it does: stores your asset-bundle definitions and the offers attached to them, and brokers BUY/SELL licensing on your behalf. It stores the bundle definition (which of your URLs a bundle covers) and your offer terms. It does **not** store copies of your content.
   * Data sent: post/page metadata you choose to register (titles, URLs, bundle groupings), your offer terms, and your PDS account identifier. Sent when you register a bundle or publish/edit an offer.
   * Endpoint is operator-configured (`PRWEB_PDS_API_BASE`); no default host is baked in.
   * Terms of Service: https://propertyrightsrsl.app/terms-of-service.
   * Privacy Policy: https://propertyrightsrsl.app/privacy-policy.

2. **Auth service (OAuth 2.0 + PKCE)**: connects your WordPress install to your PDS identity.
   * What it does: handles the OAuth authorize/exchange/refresh flow and proxies authenticated PDS calls.
   * Data sent: OAuth client id, your browser's authorization grant, and refresh/access tokens. Sent when you connect or reconnect your PDS account and on token refresh.
   * **Key custody**: your PDS account is identified by a signing key that the service generates and holds; the operator can therefore act as your PDS identity when you instruct it to. That key is not stored on this site; this plugin keeps only encrypted bearer tokens. A self-custody option is intended but is not available today. See the Terms of Service and Privacy Policy linked below.
   * Endpoint is operator-configured (`PRWEB_AUTH_API_BASE` / `PRWEB_AUTH_PUBLIC_BASE`).
   * Terms of Service: https://propertyrightsrsl.app/terms-of-service.
   * Privacy Policy: https://propertyrightsrsl.app/privacy-policy.

3. **Wallet (custodian ledger + payouts)**: holds your license earnings and runs payouts.
   * What it does: records the per-license ledger, holds/captures funds, and settles payouts (Stripe-backed).
   * Data sent: your wallet identifier, payout-policy settings, and payout requests. Sent when you view earnings, configure payout policy, or trigger a payout.
   * Endpoint is operator-configured (`PRWEB_WALLET_API_BASE`).
   * Terms of Service: https://propertyrightsrsl.app/terms-of-service.
   * Privacy Policy: https://propertyrightsrsl.app/privacy-policy.

4. **Validator**: the service crawlers hit to obtain a license token before fetching your content.
   * What it does: opens a BUY offer on PDS, mints a short-lived ticket, and releases the asset to a paying crawler.
   * Data sent: this plugin does not send your data to the validator; the validator URL is published in your licensing document so crawlers can reach it. You configure which validator URL to advertise (`pds_validator_url`).
   * Terms of Service: https://propertyrightsrsl.app/terms-of-service.
   * Privacy Policy: https://propertyrightsrsl.app/privacy-policy.

5. **UI Observability (client-side diagnostics)**: optional, **off by default**.
   * What it does: when enabled, the wp-admin browser reports JavaScript errors and basic performance/diagnostic events to help operators debug the admin UI.
   * Data sent: error messages, stack traces, route paths, and a session identifier. Personally identifying values (tokens, emails, JWTs, card numbers) are masked client-side before sending. Sent only from the wp-admin screens, and only after you turn the feature on under **Settings**.
   * No data is collected unless you opt in; the toggle defaults to off.
   * Endpoint is operator-configured (`PRWEB_OBSERVABILITY_PUBLIC_BASE`).
   * Terms of Service: https://propertyrightsrsl.app/terms-of-service.
   * Privacy Policy: https://propertyrightsrsl.app/privacy-policy.

== Installation ==

= 1. Create a PDS account =

1. Go to the PropertyRightsWeb site and sign up with your email.
2. Verify your email. Verifying activates your account and submits a starter credit funding of 1.1 żetons (1,100,000 silver leos, about $1.10) for admin review. Once approved, it can be used for on-chain actions like registering your initial assets and completing site setup. This is not a cash balance, has no cash value on its own, and cannot be withdrawn. Your real, payable balance reflects only the revenue you actually earn from licensing deals.

= 2. Install the plugin =

1. Upload `propertyrightsweb` to `/wp-content/plugins/`, or install it from the Plugins screen.
2. Activate "PropertyRightsWeb™" from the Plugins menu.

= 3. Connect and publish =

1. Open the **PropertyRightsWeb** menu and click **Connect**. You'll sign in to your PDS account (OAuth) to link it to WordPress.
2. Run **Assets → Scan** to propose asset bundles from your posts and pages.
3. Set an offer for each bundle (price, permits, prohibits) and publish.
4. Point crawlers at a validator by setting your validator URL in Settings. Use the URL for a validator you operate or one provided by a hosted service.

== Frequently Asked Questions ==

= What is an "asset bundle"? =

An asset bundle is a group of content that you license together under one price and one set of permitted and prohibited uses.

The plugin starts with these choices:

* **Features** for URLs under `/features/`.
* **Essays** for URLs under `/essays/`.
* **Uploads** for media under `/wp-content/uploads/`.
* **Unassigned** for content that does not match another bundle.
* **Custom bundle** for content you group using its URL.

You can give each bundle different offer terms. PDS stores the bundle metadata, covered URLs, and offer terms. Your actual posts, pages, and media remain on your WordPress site and are not copied to PDS.

= Do I need to install anything besides the plugin? =

The plugin works by itself for scanning and organizing your content. Licensing and payment require a connected PDS account and validator service. These external services are not installed automatically with the plugin.

= How do I point the plugin at my own services? =

Every external endpoint is operator-configured through constants in `wp-config.php`: `PRWEB_ENV`, `PRWEB_AUTH_API_BASE`, `PRWEB_AUTH_PUBLIC_BASE`, `PRWEB_OBSERVABILITY_PUBLIC_BASE`, `PRWEB_WALLET_API_BASE`, `PRWEB_VALIDATOR_INTERNAL_URL`, and `PRWEB_PDS_API_BASE`. On a local development install these fall back to `localhost` ports; on a `staging` install (set `PRWEB_ENV`) a missing value is reported as a warning, and on `prod` as a hard error. Open **Settings → API & webhooks → Required configuration** to see the status of each one; the onboarding wizard will not start the connection until `PRWEB_ENV` and the two auth base URLs are set (the remaining values matter for later steps and are reported the same way, but do not gate this step). `PRWEB_VALIDATOR_INTERNAL_URL` is the one exception; it is optional, since the validator probe already falls back to the public validator URL configured in Settings.

= How do I create a PDS account? =

Sign up with your email on the PropertyRightsWeb site and verify your email. Verification activates your account and provisions your wallet. Once that's done, connect the account inside the plugin under **PropertyRightsWeb → Connect**.

= Does the starter credit funding cost me anything, or can I withdraw it? =

No. It is a spending allowance for initial on-chain actions like registering your assets, not money in your account. It has no cash value and cannot be withdrawn or transferred. If you use more than the starter allowance, you can purchase additional usage credit, which works the same way. The only balance that is ever payable out to you is revenue you have actually earned from licensing your content, settled via Stripe-backed payouts.

= Is licensing only for AI training? =

No. Your offer terms cover the range of AI uses (training, retrieval/RAG, and others) through the permits and prohibits you set on each bundle's offer.

= Does this plugin send my content anywhere by default? =

It sends only what you choose to register. Registering a bundle or publishing an offer sends that bundle's metadata (titles, URLs, groupings) and your offer terms to PDS, never copies of your content. Nothing is sent until you take one of those actions. See the External Services section for the full list.

= Who holds the cryptographic keys? =

Two different answers, so it is worth being precise. Your publisher signing key is generated and held by the service you connect to, not by this plugin and not on this site; the operator can act as your PDS identity when you instruct it to. An option to hold your own key is intended but is not available today. Separately, when a visitor takes a free access license, the plugin creates a PDS identity for that visitor and stores its key, encrypted, in your own WordPress database; those reader keys never leave your site, and securing them is part of securing your site. The plugin's legacy fallback connection mode also stores a publisher key in your database rather than using OAuth; it is off by default.

= Is the client-side diagnostics (UI Observability) reporting on by default? =

No. It is off by default. You must enable it under the plugin's Settings screen. When off, no diagnostic data leaves the browser.

= Do I need to run my own validator? =

You or a service provider operates a validator that crawlers contact to buy a license. The validator URL you configure is published in your licensing document.

= What PHP and WordPress versions are required? =

WordPress 6.4 or newer and PHP 8.2 or newer.

= Where do payouts come from? =

License earnings are recorded by the custodian wallet service and settled via Stripe-backed payouts. Earnings accumulate until you request a payout; funds are not released on an automatic schedule. Each request is reviewed before money leaves, normally within one business day. You will need to complete the payment processor's identity checks before your first payout.

== Screenshots ==

1. Dashboard. Vital signs for your publisher account: 30-day earnings, licensed crawls, active buyers, and system health.
2. Content. Scan posts and pages and group them into asset bundles for registration.
3. Offers. Configure SELL offer terms (price, permits, prohibits) for your bundles.
4. Wallet. Earnings detail and payout policy.
5. Settings. Connection, network, and the opt-in UI Observability toggle.

== Changelog ==

= 0.4.3 =
* Author URI now points at https://personaldigitalspaces.io/, the domain of the plugin author's WordPress.org account. No functional changes.

= 0.4.2 =
* Static rsl.xml is now written to the site root, not the WordPress install directory, so subdirectory installs (WordPress in /wp, site at /) publish it where crawlers look. If the root cannot be determined reliably, the plugin refuses to write the file instead of guessing. On update, a stale rsl.xml left in the install directory by earlier versions is removed, and uninstall removes it too.
* Security: the connect flow is now tied to the administrator and login session that started it. A different administrator, or a second login of the same administrator, can no longer complete or cancel someone else's pending connection.
* The webhook signing secret is now stored exactly as entered. Previously some characters were silently stripped, which made webhook verification fail. A secret that is not printable ASCII without spaces, 16–256 characters, is now rejected with a message, and the existing secret is kept.
* Settings: errors and the "Settings saved." notice now appear on the plugin's settings screen.

= 0.4.1 =
* Security: database queries in admin statistics, asset registration, the events store, offer defaults and the admin menu now go through $wpdb->prepare(), with table names bound as %i identifiers instead of interpolated into the SQL string.
* Script and style handles, localized JavaScript globals, and the uploads log directory now use the plugin's own prefix, so they cannot collide with other plugins or themes.
* Settings and the onboarding wizard now check the required wp-config.php values and report which ones are missing or malformed. Connecting is blocked on the server until they are set, not only in the browser.
* Registering an asset without enough credit now shows a readable message instead of the raw service response.
* Offers: the filter bar no longer appears on the offer detail view.
* Diagnostics: the copy button stays hidden until a probe result exists.

= 0.4.0 =
* Renamed to PropertyRightsWeb™. RSL is removed from the plugin name, the slug, the text domain and the plugin URLs; the plugin still implements the RSL standard and the documentation below still describes it.
* Plugin URI now points at the plugin's own landing page.
* Documentation: stated explicitly that the plugin implements the RSL open standard and is not affiliated with or endorsed by the RSL Collective.

= 0.3.9 =
* Make anonymous reader registration resumable with idempotency keys and persisted partial state.
* Return correlated JSON errors for configuration, upstream, timeout, and unexpected failures.

= 0.3.8 =
* WP.org submission readiness: reconciled the plugin version across header, constant, and stable tag; added External Services, FAQ, and Screenshots sections; corrected the install slug; made client-side UI Observability opt-in (off by default).
* Documentation: rewrote for a publisher audience. Added "what you need to get started," PDS-account creation steps, an asset-bundle explainer, and a source-repository link; clarified that licensing covers all AI uses (not only training).
* Key custody disclosed: the connect and identity screens now name who holds the publisher signing key instead of only stating that it is not kept on the site, and a new FAQ covers publisher keys, reader keys stored in your own database, and the legacy fallback.

= 0.0.1 =
* Scaffold release. Plugin shell, admin pages, DB tables, action scheduler hook.
