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]>
122 lines
7.9 KiB
Markdown
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.
|