@kehto/paja 0.18.1 → 0.20.0

package/README.md

@@ -232,39 +232,27 @@ The file opens in a new runtime tab named after the file.
 
 ## 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. Required or optional INC declarations are eligible only when
-INC is available in the target's host-resolved environment. Missing optional INC
-still permits frame loading. Nameless root/snapshot artifacts may also run, but
-are excluded from the dTag-keyed intent 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 `intent.deliver`
-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`.
-
-Reusing a handler tab activates it and remembers the new active tab. Paja's stage
-shows exactly one tab, so a delivered intent always selects the handler tab:
-`behavior.focus` is a hint, and honoring `false` as "deliver into the hidden
-tab" would report a handled intent whose surface the user never sees. Reuse
-still leaves the caller's tab open, so nothing is replaced. Newly created
-handler tabs behave the same way. Pointer installation logs declared
-archetypes and required domains; Paja warns when archetypes lack `inc`, which
-its current convention delivery policy requires.
+Paja stores immutable resolver-verified manifest facts separately from live tabs.
+Closing a frame leaves its catalog record available for cold starts; explicit
+artifact removal deletes it. Restored pointers are reverified before entering the
+catalog. Entries preserve exact conventions and ordered parameter names under
+publisher/kind-safe opaque IDs, including nameless root and snapshot artifacts.
+The target's resolved `intent` domain must be available; INC is not required.
+
+Selection uses exact contracts and user-owned default, chooser, recommendation,
+and explicit-authorization policy. Explicit handler IDs require sender-aware
+authorization and cannot address an arbitrary running frame.
+
+The controller retains work before returning acceptance. It then opens or reuses
+a verified target, waits for its registered source and real `shell.ready`, checks
+that the generation is current, and sends one target-only `intent.deliver`.
+Replacement, readiness failure, and terminal send failure remain host-observable
+controller outcomes; they do not produce a second source result. Accepted work
+survives source teardown and is never replayed by tab restoration.
+
+Paja activates delivered handler tabs because its stage shows one tab at a time.
+`behavior.focus` is advisory; `reuse: false` creates a new surface. Existing caller
+tabs remain open. Installed contracts and domains appear in pointer diagnostics.
 
 `@napplet/shim@0.30.0` supplies no generic shell API. Kehto deliberately keeps
 its host-owned mandatory `window.napplet.shell` prelude: it installs the live
@@ -273,16 +261,31 @@ 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, WebAssembly compilation through
-the narrow `'wasm-unsafe-eval'` source, `data:`/`blob:` images, and `data:` fonts;
-keeps JavaScript string evaluation blocked; 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.
+Before Paja assigns a verified runtime-pointer document to `srcdoc`, it calls
+`@kehto/shell`'s `prepareNappletSrcdoc`. The shell inserts validated CSP first,
+then the mandatory namespace. Defaults permit inline script/style, WASM byte
+compilation, `data:`/`blob:` images and `data:` fonts, and deny other resource
+classes. Paja grants direct connections only to resolved relay and Blossom
+origins plus explicit host grants.
+
+Hosts can pass `csp` to `createPajaRuntimeHostConfig`:
+
+```ts
+const config = createPajaRuntimeHostConfig({
+  pointer,
+  csp: {
+    connectOrigins: ['https://api.example'],
+    directives: { 'media-src': ['blob:'], 'img-src': ['data:'] },
+  },
+});
+```
+
+The shell rejects broad JavaScript evaluation, non-origin connection grants,
+and script policies that block its bootstrap. NIP-5D's CSP recommendations are
+enforced; individual baseline source lists remain configurable. Existing
+artifact CSP is retained. Set `frame-ancestors` on the host HTTP response, not
+in a meta policy. See the [shared policy contract](https://github.com/kehto/web/blob/main/docs/policies/NIP-5D-CONFORMANCE.md#shell-csp-enforcement).
+Local target-URL authoring mode retains its separate development policy and HMR.
 
 Environment simulation can be supplied through CLI flags or a JSON config file:
 
@@ -461,10 +464,50 @@ Generated API module: `docs/api/modules/_kehto_paja.html` (run `pnpm docs:api`).
 
 ## NIP-5D event compatibility
 
-Current manifests use a direct artifact `x` hash, plain-text `content`, independent
-`z`/`i` routing declarations, and required `R` / optional `O` domains. Kehto also
+Current manifests use a direct artifact `x` hash, plain-text `content`, role-matched
+`z`/`i` intent declarations, and required `R` / optional `O` domains. Kehto also
 accepts legacy aggregate events through an isolated compatibility adapter.
 Existing `aggregateHash` host/cache/ACL fields carry the verified artifact hash
 for current events; legacy identities keep their original aggregate. Both paths
 verify signatures and bytes before runtime injection and `srcdoc` execution.
 For the schema and removal boundary, see [event migration](https://kehto.github.io/web/docs/migrations/NIP-5D-EVENT-SCHEMA.html).
+
+## NAP-INTENT links and lifecycle
+
+This follows [NAP-INTENT PR #106](https://github.com/napplet/naps/blob/fc121fc264615482143eda86125863d2e1f741a2/naps/NAP-INTENT.md) at `fc121fc264615482143eda86125863d2e1f741a2` and NIP-5D PR #2303 at `020cb8b33a9e4c6b8ca4b2f9d0ed0a67843b68f7`.
+
+For a verified app with advertised intents, choose **Share → Create intent link**.
+Select its convention, include the text parameters you want, or switch to JSON.
+Parameters start omitted; selecting Include with an empty field sends an explicit
+empty string. Names stay in advertised order and extra named fields are allowed.
+No parameter type or requiredness is inferred. An empty advertised list still
+permits a payload. Opening or editing the builder never invokes an intent.
+Use **Copy link** or explicitly **Test intent** to open the review view.
+
+The outer URL carries a complete percent-encoded convention URI in `intent`.
+For example, `?intent=napplet%3Aprofile%2Fopen%3Fpubkey%3Dabc%252B123`
+contains `napplet:profile/open?pubkey=abc%2B123` and delivers text `abc+123`.
+Outer and inner layers decode once each; literal `+` stays plus. Optional outer
+`payload` contains JSON, including null, primitives, arrays, or objects, and
+cannot accompany an inner query. URLs are limited to 16 KiB UTF-8. Duplicate
+keys, malformed encoding, and conflicting target instructions are rejected.
+Ordinary pointer-only app links retain their existing behavior.
+
+Choose recipient default routing, a named-35129 `#naddr` recommendation, or an
+exact outer `pointer`. Explicit pointers must verify and advertise the exact
+contract; failure never silently falls back. Otherwise an applicable user default
+wins before a recommendation, then ordinary compatible selection applies.
+Recommendation relay hints remain untrusted discovery inputs. Installing a
+recommendation requires confirmation after signed metadata and bytes verify.
+
+Incoming links show **Review intent** before execution. Edit, choose another
+handler, explicitly save or clear a default, launch, retry, or cancel. Defaults
+never change implicitly. Cancellation before Launch sends nothing; accepted
+work is retained while completion or failure remains visible in the host.
+
+Paja invokes through a separate signed launcher napplet with a verified artifact
+and authenticated iframe endpoint. Its source supplies the opaque sender; the
+URL cannot supply one. The hidden launcher is removed after acceptance and is
+never persisted or restored. Verification precedes `srcdoc`, and host bootstrap
+injection stays outside signed bytes. Native external-origin sender semantics
+remain a documented upstream spec gap; no host sender identity is invented.