winzik/docs/embed.en.md
David Nurdin 87ad5126aa Embed kit and docs: a playground application on a partner's site without iframe nor CORS, and custom domains
tools/embed/jumphp-embed.php: one PHP file (7.4+, curl) that signs the requests to the
playground's /api/embed/<slug>/ (HMAC-SHA256 over method, path, query, time and body
hash), serves the application under the partner's base path (streamed, Range, gzip
passed through, immutable files kept on disk), relays the TCP tickets with the
visitor's address, and gives the blocks (disk cache, ETag revalidation, last copy when
the playground is down); no cookie either way, security headers. Its end-to-end test
(tools/embed/tests/test.sh, Docker), the WordPress plugin (shortcode
[jumphp_block app block], the base path answered at plugins_loaded, settings page,
secret possibly in wp-config.php), nginx / Caddy / plain PHP examples.

docs/embed.md (+ .en), docs/domains.md (+ .en), AGENTS.md section 14.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-14 02:41:11 +01:00

122 lines
7.9 KiB
Markdown

# Embedding a JumPHP application on a partner's site
An application published on the playground (https://jumphp.net) can appear on another site **as one of its own pages**: no
iframe, no CORS, same origin. Search engines see the HTML on the partner's site (a `canonical` to its address), and the
application gets the visitor's **provenance** (the site they came from) and the fields of the form that sent them.
Real case: `caramail-chat` on https://caramail.tv: a login form at the top of every page (a *block* served by the application,
updated with it) that sends to https://caramail.tv/chat/, where the application runs as if it were hosted there.
```
browser ──► caramail.tv/chat/... ──(signed request)──► jumphp.net/api/embed/caramail-chat/app/...
partner's server ◄──── answer ─────── (rewritten page, engine, files)
(jumphp-embed.php kit)
browser ──► wss://jumphp.net/tcp (TCP bridge, direct: a WebSocket has no CORS)
```
## 1. The application (the project)
`config/project.yaml`:
```yaml
project:
embed:
blocks: [login] # site/blocks/login.html: HTML fragments the partner shows
params: [nickname, age, city, sex] # the form fields passed to the application (first scene)
```
- A block is an HTML fragment (`site/blocks/<name>.html`), no `<html>`: a form, a banner, a list of rooms… `{{BASE}}` becomes the
application's address on the partner's site (`https://caramail.tv/chat`), `{{SITE}}` its domain, `{{APP}}` the slug. Its
pictures: `{{BASE}}/site/images/logo.png` (the files of `site/` are relayed too).
```html
<form class="jumphp-login" method="get" action="{{BASE}}/">
<input name="nickname" required maxlength="20" placeholder="Nickname">
<button>Enter the chat</button>
</form>
```
- The **params** reach `enter()` / `loaded()` of the first scene, over project.yaml's `start_params`: only the names declared in
`embed.params`, as strings, and **always `site`** = the partner's domain (set by the playground from the signature: never what
the visitor could type in the address).
- The form may be `method="get"` (fields in the address) or `method="post"` (the kit relays them as they are).
- A terminal application (`kind: cli`) cannot be embedded yet. Games, graphic apps (`kind: gui`) and desktop apps in the browser
(`ui: webview`) can.
How the engine gets the params: the page sets `window.JUMPHP_GAME.start_params` (→ constant `JUMPHP_START_PARAMS`, merged by
`Engine::startParams()` over `start_params`) and `tcp_ticket_url` (→ `JUMPHP_TCP_URL`) in the engines released after JumPHP 0.5.53; for **every** engine
version, the playground also serves that page a `config/project.yaml` that already holds these `start_params` and this
`tcp_ticket_url` (the params travel sealed, HMAC, from the page to its manifest).
## 2. The playground (the project's owner)
Studio → the project → **On a partner's site**: domain (`caramail.tv`), base path (`/chat`) → **Add**. The studio gives:
- the site's **identifier** (`JUMPHP_EMBED_SITE=es_…`, public);
- the shared **secret** (`JUMPHP_EMBED_SECRET=jes_…`, kept encrypted, shown to the owner only).
The owner can disable / enable it, **renew the secret** (the old one stops at once) or delete it. The administrator sees every
partner site (Administration → *Partner sites and domains*) and can **cut** one (with a reason): the owner cannot restore it.
## 3. The partner: the kit
`tools/embed/jumphp-embed.php`: one PHP file (7.4+, curl), no dependency. It:
- serves the application under the base path: `/chat/` = the page, and everything it loads (`engine/<version>/…` the shared engine
and its wasm, `manifest.json`, `files/…`, `private/…`, `embed-config.yaml`, `site/…`);
- signs each request and relays it **streamed** (big files never sit in memory), with `Range`, `If-None-Match`, and the
playground's gzip passed through;
- keeps immutable files **on disk** (`?v=<hash>` addresses and the engine's versioned folder, up to 64 MB) and then serves them
itself (Range included);
- keeps the **blocks** on disk (`ttl`, 300 s by default), revalidates them with their ETag, and returns the last copy when the
playground does not answer;
- relays the **TCP bridge ticket** (`/chat/api/tcp/ticket`) and the runtime wake-up (`/chat/api/runtime/wake`) with the visitor's
address (`X-JumPHP-Client-IP`);
- **never** forwards the visitor's cookies to the playground, nor the playground's cookies or `X-Robots-Tag` to the visitor; adds
`X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options: SAMEORIGIN`.
Settings (an array or environment variables): `server` / `JUMPHP_EMBED_SERVER` (`https://jumphp.net`), `app` / `JUMPHP_EMBED_APP`,
`site` / `JUMPHP_EMBED_SITE`, `secret` / `JUMPHP_EMBED_SECRET` (never in git nor in a public file), `base` / `JUMPHP_EMBED_BASE`,
`cache` / `JUMPHP_EMBED_CACHE`, `ttl` / `JUMPHP_EMBED_TTL`.
```php
require '/srv/jumphp-embed/jumphp-embed.php';
$jumphp = JumphpEmbed::fromConfig(['app' => 'caramail-chat', 'base' => '/chat']); // site, secret: the environment
if ($jumphp->serve()) { exit; } // /chat/...: answered; otherwise the site goes on
echo $jumphp->block('login'); // in a page
```
Ready examples: `tools/embed/examples/nginx.conf`, `tools/embed/examples/Caddyfile`, `tools/embed/examples/front.php`. Fastest:
nginx / Caddy send `/chat/` straight to the kit without loading the CMS. Its tests: `tools/embed/tests/test.sh` (Docker).
### WordPress
`tools/embed/wordpress/build.sh` makes `jumphp-embed.zip` (Plugins → Add → Upload). Settings → **JumPHP Embed**: the playground's
address and one line per application (slug, identifier, secret, base path). The secret can stay out of the database:
`define('JUMPHP_EMBED_SECRET_CARAMAIL_CHAT', 'jes_…');` in `wp-config.php`.
- Shortcode: `[jumphp_block app="caramail-chat" block="login"]` (a page, a widget, or `do_shortcode()` in the theme's header).
- The base path (`/chat/…`) is taken at `plugins_loaded`, before the theme and WordPress's query. A page cache must exclude `/chat/`.
## 4. The TCP bridge
A page asks its ticket from **its own origin** by default (`/api/tcp/ticket`). On the partner's site that origin is `caramail.tv`,
so the embedded page asks `https://caramail.tv/chat/api/tcp/ticket` (`tcp_ticket_url`), which the kit relays, signed. The ticket
names the bridge `wss://jumphp.net/tcp`, opened directly by the browser (a WebSocket is not subject to CORS), with the same
administrator approvals (docs/tcp.md). Every HTTP request stays same-origin, and the tickets API is not opened to every site's CORS.
## 5. The API (to write another kit)
Headers of every request: `X-JumPHP-Site` (`es_…`), `X-JumPHP-Time` (Unix time, refused beyond **300 s** from the playground's
clock), `X-JumPHP-Signature` = hex HMAC-SHA256(secret, `METHOD\npath\nquery\ntime\nsha256hex(body)`), path and query as sent
(encoded, query without `?`), compared in constant time. Test vector: secret `s3cret`, `GET /api/embed/a/block/login`, time `1000`,
no query nor body → `hash_hmac('sha256', "GET\n/api/embed/a/block/login\n\n1000\n" . hash('sha256', ''), 's3cret')`.
| Request | Answer |
|---|---|
| `GET /api/embed/<slug>/block/<name>` | the block, `ETag`, `Cache-Control: public, max-age=300`, 304 on `If-None-Match` |
| `GET\|POST /api/embed/<slug>/app/` | the rewritten page (`<base>`, relative engine and files, `canonical` / `og:url` on the partner); query and POST body give the params |
| `GET /api/embed/<slug>/app/<path>` | `manifest.json`, `embed-config.yaml`, `files/…`, `private/…`, `packages/…`, `app/…`, `engine/<version>/…`, `site/…` |
| `POST /api/embed/<slug>/tcp/ticket` | the bridge ticket (`X-JumPHP-Client-IP`: the visitor's address) |
| `POST /api/embed/<slug>/runtime/wake` | the runtime wake-up |
Errors as JSON `{"error": "..."}`: 401 (signature missing, wrong, too old, unknown site), 403 (off, or cut by the administrator),
404 (not published, undeclared block, missing file), 405.