@kehto/paja 0.8.0 → 0.10.0

package/README.md

@@ -17,7 +17,8 @@ The target URL is explicit on purpose. Kehto can spawn any framework command and
 wait for that URL, but it does not guess which URL the framework chose. Loading
 that URL through Paja as injected `srcdoc` lets Kehto install mandatory
 `window.napplet.shell` plus enabled optional domains before app code runs. The
-shell shim completes `shell.ready` / `shell.init` and caches capability queries,
+Kehto host-owned shell prelude completes `shell.ready` / `shell.init` and caches
+capability queries,
 while a `<base>` tag keeps the
 app's own assets and HMR pointed at the target dev server without Vite, Svelte,
 React, or any other framework lock-in.
@@ -34,13 +35,37 @@ mode. `shell` is the mandatory, non-toggleable handshake domain; the deprecated
 path remains an upstream compatibility alias to `inc`. The upstream `dm` domain
 is not advertised until Paja wires a deterministic development DM backend.
 
+## Dev-server CORS requirement
+
+The target iframe is sandboxed without `allow-same-origin`, so the napplet
+document has an opaque origin and requests its own assets with `Origin: null`.
+`<script type="module">` is always fetched in CORS mode, so a dev server that
+does not allow that origin blocks the napplet's entry module and the frame
+renders blank. Vite's default `server.cors` allowlist covers only `localhost`,
+`127.0.0.1`, and `[::1]` origins, so it rejects `null`:
+
+```js
+// vite.config.js
+export default {
+  server: { cors: { origin: '*' } },
+};
+```
+
+Any dev server works as long as it answers `Origin: null` with
+`Access-Control-Allow-Origin: *` or `null`. Paja probes the target on startup
+and logs a `paja.target.cors.error` entry in the message log, plus a console
+warning, when the target would block the sandboxed frame.
+
 The console shows supported interfaces with per-domain injection toggles,
 runtime ACL controls, signer controls, and a filterable message log with visible
 error details. Paja auto-connects a browser NIP-07 signer when `window.nostr` is
 available, can connect to a bunker/NIP-46 URI, and only uses the generated local
 development signer when the Dev signer button is selected. Every signing or
 publish operation still uses a browser confirmation prompt. There is no bypass
-list.
+list. A denied prompt or a live publish with no accepting relay returns a
+canonical failure and is not added to Paja's in-memory relay view. Paja's
+scoped-relay hook likewise waits for the backend result and returns `false`
+after denial or transport failure.
 
 The static Paja Runtime build is served at `/web/paja/` in the GitHub Pages
 artifact. It uses the same browser host and service adapters, but loads verified
@@ -53,6 +78,47 @@ runtime tabs in local storage so returning to `/web/paja/` restores the previous
 pointer set. An explicit pointer in the URL still takes precedence over restored
 tabs.
 
+## Installed intent handlers and delivery
+
+Paja keeps resolver-verified pointer and manifest facts in an installed catalog,
+separate from the live tab/controller map. A verified install inserts or replaces
+the catalog record; an explicit artifact removal removes it. Closing, reloading,
+or replacing a frame never makes an installed handler unavailable, so a cold
+target can still be selected and started later.
+
+Intent selection considers only exact compatible contracts from that catalog.
+Paja can use a compatible user default, ask its host chooser when more than one
+candidate is available, or reject an ambiguity. An explicit handler d-tag is
+accepted only when it is an installed compatible handler and the invoking sender
+has been explicitly authorized for it. It is not a request to deliver to an
+arbitrary running frame.
+
+When Paja receives an invocation, it selects and opens or reuses a verified
+target. The controller waits for the target generation's
+registered `MessageEvent.source` to establish its real `shell.ready` session;
+it checks that generation is still current, sends one target-only `inc.event`
+with the selected queryless convention, and returns the final handled target
+identity. A superseded target/source, failed open/readiness, or terminal send is
+handled by the controller's replacement/retry/terminal policy and produces a
+canonical failed `IntentResult`.
+
+`@napplet/shim@0.29.0` supplies no generic shell API. Kehto deliberately keeps
+its host-owned mandatory `window.napplet.shell` prelude: it installs the live
+receiver before the one bare `shell.ready`, caches the first `shell.init`, and
+provides local `ready()`, `supports()`, read-only `services`, and one-shot
+`onReady()`. This is the documented upstream-package-drift exception, not a
+shim capability.
+
+Before Paja assigns a verified runtime-pointer document to `srcdoc`, it inserts
+Kehto's local Class-1 CSP before the host-owned namespace prelude. The policy
+denies all defaults; permits inline script/style, `data:`/`blob:` images, and
+`data:` fonts; grants `connect-src` only to the resolved relay and Blossom
+origins; explicitly denies worker, child, frame, media, object, manifest,
+prefetch, base, and form capabilities; and ends with `frame-ancestors 'self'`.
+The NIP-5D verified-srcdoc and opaque-sandbox rules do not mandate this CSP;
+it is Kehto policy. Local target-URL authoring mode is intentionally outside
+this verified-artifact policy path.
+
 Environment simulation can be supplied through CLI flags or a JSON config file:
 
 ```bash