## Problem/Motivation Kessai's contract is answerable by something other than the engine: `kessai` declares its own service name, an implementation announces itself with the `kessai_payment_client` tag, and every method takes and answers with values. Nothing implemented it remotely, so the claim was untested. The reason to want one is not symmetry. A site that handles cards is a site with obligations, and those obligations should not spread to every site that needs to take a payment. Putting the engine on one host lets the sites that ask for payments stay out of scope. Three things stood in the way: 1. **Nothing spoke HTTP.** The contract was in-process only. 2. **A consumer cannot subscribe to another site's dispatcher.** Consumers react to `PaymentEvents`, and a remote one would hear nothing. 3. **The payer could not come home.** `Payment::getHandoffUrl()` builds a route on the engine and `OnwardUrl` refuses anything external, so a remote consumer's payer would pay and land on the engine's front page. ## Proposed resolution Two submodules. ### `kessai_server` An OAuth-gated HTTP transport over `PaymentClientInterface`. It holds no payment logic: the route authenticates, the scope narrows, the engine does the work. Authorization is the part that is not a copy, because kessai has no tenant and no current user: - **A consumer targets exactly one payment account**, read from the consumer and never from the request - where the money lands is the site owner's decision. Fail closed: a consumer with no account takes no payment. - **A payment belongs to the consumer that created it**, recorded in a column on the payment. A read or a write against another consumer's payment answers 404, not 403: a refusal would confirm it exists. The column rather than a correlation table, because the engine asks the same question itself. Two consuming sites number their own content, so `node 42` on one is `node 42` on the other; without the consumer in the re-entry search, a site sharing an account would be handed the other's standing payment, and every site creating a payment for one subject would serialize against every other on one lock. - **A consumer's payer may only be returned to an origin the site owner registered** for it, checked where the address enters rather than when the payer is being redirected. ### `kessai_client` `RemotePaymentClient` implementing `PaymentClientInterface` over that API, with `RemotePayment` and `RemoteMovement` built from JSON, a client-credentials token provider keyed through `key`, and a `kessai_remote` config entity per account the site can pay into. It tags itself `kessai_payment_client` above the engine's priority, so a site installing it settles remotely without touching a line of consumer code. It depends on `kessai` and **not** on `kessai_engine`: a consumer site has no engine, no payment tables and no cron. **A payment carries the uuid of the account it was taken at**, which is what routes a later call back to the host holding it - including a payment arriving on its own, carrying nothing the consumer site put there. The uuid is read during the handshake, which also settles whether the credentials work and whether the two sides can read each other. ### Events across the boundary Every event a payment announces is posted to the consumer that took it and announced there under the same `PaymentEvents` constant, carrying the same `PaymentInterface`, so a subscriber written against a local kessai needs no change. `PaymentEvent::isHandled()` travels back, so a default reaction on the engine stands down. The address is worked out rather than configured: the consumer's site, then a path both ends agree on, then the uuid of the account. The engine holds both - the uuid is its own account's, and the site is the origin it already registered - so an engine answering a thousand sites stores one address each and nothing about how any of them is built. The body is signed with a secret minted per consumer and handed over during the handshake, over the connection the client is already authenticated on. The timestamp is inside the digest, so a notice recorded off the wire cannot be freshened and replayed. Delivery is best effort and logged; a retry queue is deliberately not built. ### Letting the payer home `OnwardUrl` gains a caller-supplied allowlist of origins, empty by default, so same-site behaviour is unchanged. An origin is a scheme, a host and a port compared exactly - never a prefix - and a value that is not an origin, or would carry a payment in clear text, is refused where an operator types it. Where the payer comes home is said on `PaymentRequest`, which is the only place a consumer settled elsewhere can say it: the link to the provider is minted on the engine from its own hash salt. A site with an engine records the same field from the same request. ## User interface changes A remote payment account list and form on a consumer site, showing which account the credentials land in and whether notices are arriving. Three fields on the consumer over on the engine: the account its money lands in, the origins its payer may return to, and - only where the origins do not answer it - which site it is. ## API changes `PaymentClientInterface` could not be implemented remotely as it stood, which is the finding the issue was opened for. Pre-1.0, so the changes land here: - `PaymentInterface::getConsumer()`. - `PaymentRequest::$consumer` and `PaymentRequest::$returnUrl`. - `PaymentQuery::$consumer`. - `$metadata` and `$consumer` on `authorizeToken()` and `chargeToken()`. - `PaymentWire`, `PaymentNotice`, `Origin` and `HttpsPolicy` join the contract, because both ends need them and neither is installed beside the other. ## Data model changes A `consumer` column on `kessai_payment`, empty for a payment a site took for itself. Three base fields on `consumer`, added by `kessai_server`. AI-Generated: Yes (Claude Code was used to help draft this issue summary.)