@kehto/paja 0.17.1 → 0.19.0

package/README.md

@@ -57,6 +57,15 @@ Any dev server works as long as it answers `Origin: null` with
 and logs a `paja.target.cors.error` entry in the message log, plus a console
 warning, when the target would block the sandboxed frame.
 
+Every drawer section is a flush, independent native accordion: **Pointer** (in
+runtime-pointer mode), **Interfaces**, **ACL**, **Signer**, **Resource servers**,
+then **Messages** last. Headers support Enter/Space, visible keyboard focus and
+state chevrons; bodies keep their padding and live controls when hidden. Sections
+start expanded unless a validated origin-local boolean preference says otherwise.
+The collapsed map uses `kehto:paja:sidebar-sections:v1`, separately from whole-drawer
+visibility and resource server values. Storage failures leave session-only toggles
+usable; collapsing never reloads the running app or discards unsaved drafts.
+
 The console shows supported interfaces with per-domain injection toggles,
 runtime ACL controls, signer controls, and a filterable message log with visible
 error details. It starts expanded and collapses to the left with the chevron
@@ -193,6 +202,34 @@ and hinted-author/publisher server lists first, then the active shell user's
 published list, the current window's verified pointer-manifest servers, and
 finally configured runtime fallbacks.
 
+## Local `index.html` files
+
+In runtime-pointer mode, Paja can also open a napplet straight from disk. Use
+**Open file…** next to **Load**, or drop an `index.html` anywhere on the Paja
+page (not onto a running napplet frame, which receives its own drag events).
+The file opens in a new runtime tab named after the file.
+
+- **Identity comes from the bytes.** Paja hashes the exact file bytes (`sha256`)
+  and derives `aggregateHash` as the NIP-5A aggregate over the single
+  `/index.html` path entry. That is the same derivation the resolver checks for a
+  published single-file napplet, so editing the file gives it a new identity. The
+  `dTag` comes from the NIP-5D publishing metadata
+  `<meta name="napplet-id" content="…">`. Without it, Paja uses
+  `local-<file-stem>`.
+- **Same loading path as verified pointers.** Paja registers the identity before
+  the frame runs. It injects the Class-1 CSP (with `connect-src 'none'`, since a
+  local file has no relay or Blossom hints) and then the runtime-owned
+  `window.napplet` prelude, including mandatory `shell`. The bytes go in through
+  `srcdoc` under the same `allow-scripts` sandbox.
+- **Development only and unverified.** A local file has no signed manifest. It
+  never enters the installed napplet catalog, never becomes an intent delivery
+  target, has no share link, and is not restored after a page reload.
+- **Self-contained single-file HTML only.** A `srcdoc` document has no base URL,
+  and the CSP denies network loads, so relative `<script src>`, stylesheets, and
+  images do not load. Paja lists relative references it finds in the status line
+  and the message log. Build with an inlining bundler (for example
+  `vite-plugin-singlefile`). Opening a folder or zip of assets is not supported.
+
 ## Installed intent handlers and delivery
 
 Paja keeps resolver-verified pointer and manifest facts in an installed catalog,
@@ -201,7 +238,10 @@ 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.
+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
@@ -211,7 +251,7 @@ 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`
+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
@@ -233,16 +273,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:
 
@@ -318,6 +373,25 @@ pubkey without `signEvent` is read-only. This implements the draft
 
 ## NAP-RESOURCE schemes
 
+The development sidebar's **Resource servers** textarea adds read-only Blossom
+lookup origins in both target-URL and runtime-pointer modes. Enter one public
+HTTPS origin per line (`cdn.example` is shorthand for `https://cdn.example`)
+and press **Save**. Blanks are ignored and equivalent origins are deduplicated
+in first-seen order. A bad line rejects the whole save without changing the
+active or saved list; credentials, paths, queries, fragments, HTTP and obvious
+local/private hosts are rejected. Saving blank clears only these extras.
+
+Valid saves apply to subsequent Blossom requests across all running tabs,
+without reloading their frames. The list persists in the host origin's
+`localStorage`; if storage fails, it remains usable **session-only**, and the
+status warns that an older saved list may return after reload. Extras are
+appended after existing request/event/user/window/configured defaults. The
+combined eight-server cap remains: extras may not be reached if earlier
+candidates fill it. This setting does not change upload destinations,
+per-napplet NAP-CONFIG, initial pointer/artifact loading, direct HTTP(S) resource
+URLs, or napplet CSP/network grants. Browser CORS and the DNS limitation below
+still apply.
+
 Paja's developer-runtime policy accepts arbitrary `http:` and `https:` resource
 URLs so a normal remote image does not look broken merely because its origin was
 not pre-granted. Paja resolves those URLs with browser `fetch`, omits credentials
@@ -325,33 +399,68 @@ and referrer data, caps responses at 10 MiB, and classifies MIME from returned
 bytes. Its byte classifier recognizes checksum-valid Game Boy ROM headers as
 `application/vnd.nintendo.gb-rom`; it never trusts a server-supplied media type.
 Browser network and CORS rules still apply: an unreadable response is the
-canonical `network-error`, while any CORS-readable response is returned as NAP
-bytes.
+canonical `network-error`. HTTP(S) and locally decoded `data:` bytes must have a
+recognized type; opaque invalid-UTF-8 or NUL-bearing binary remains rejected.
+Only capped, SHA-256-verified canonical Blossom resources may return unknown
+opaque bytes as `application/octet-stream`. Recognized formats retain their
+sniffed MIME. SVG, HTML, XML and script prefixes remain blocked, even with NUL or
+invalid-UTF-8 suffixes; upstream headers never override classification.
+Byte-identifiable UTF-16 markup is checked by decoding the complete capped
+buffer; identifiable UTF-32 document signatures are conservatively rejected.
+This encoding guard is not a general markup parser.
 
 `data:` remains locally decoded. `blossom:` is a separate, content-addressed
 boundary and is advertised because each request may provide server locations
-without a host default. Paja accepts only public-looking HTTPS origin hints,
-discards invalid/private literals, and deduplicates them. For a canonical URL
+without a host default. For example, reads accept
+`blossom:<hash>.gbc?xs=cdn.example&as=<pubkey>&sz=32768` and
+`blossom:sha256:<hash>.gbc?xs=cdn.example&sz=32768`.
+Repeated `xs` and `as` are supported without an observed event. Paja accepts only
+public-looking HTTPS origin hints (scheme-less domains use HTTPS), discards
+invalid/private literals, and deduplicates them. Unlike BUD-10's suggested HTTP
+retry, URI hints never enable public HTTP. For a Blossom URL
 previously returned to the same napplet window by `outbox.getEvent`,
 `outbox.query`, or `outbox.subscribe`, Paja retains bounded event context
-without prefetching bytes. Resolution tries request and
-event-local server hints first, then lazily queries hinted authors' and the
+without prefetching bytes. Resolution tries explicit request servers, URI `xs`,
+and event-local server hints first, then lazily queries URI `as`, event-hinted authors' and the
 event publisher's newest BUD-03 kind `10063` lists through the verified
 NIP-65-aware OUTBOX router, then queries the active shell user's BUD-03 list
 through that same router, then uses the current window's verified
-pointer-manifest servers, followed by upload-runtime fallbacks. The user-list
+pointer-manifest servers, followed by upload-runtime fallbacks and saved extra
+resource servers. The user-list
 lookup works independently of upload mode; an upload runtime may reuse the same
 servers when present. ROM-specific event and publisher locations retain
-priority over the user/runtime fallbacks. The combined list is capped at eight
-candidates. The only accepted identifier is `blossom:sha256:<hex>`;
-Paja refuses redirects, verifies the requested SHA-256, and permits plain-HTTP
+priority over the user/runtime fallbacks. URI length is capped at 8192 characters;
+retained unique `xs`, the complete author lookup list, and combined server
+candidates are each capped at eight. Both prefixes require exactly 64 hex
+characters, with an optional single ASCII-alphanumeric extension preserved in
+`GET /<hash>.<ext>`; no query hints reach the blob server. Extensions and upstream
+headers never establish MIME. Fragments, path injection, malformed escapes/authors,
+and invalid or repeated `sz` fail with `invalid-request` before discovery.
+`sz` must be a positive decimal safe integer; sizes above 10 MiB fail `too-large`.
+Paja checks a numeric Content-Length before reading and always checks actual
+bytes against `sz`; a size or hash mismatch is `decode-failed` unless fallback succeeds.
+Hash-only event context stays window-scoped, without transferring extension/size
+or retaining request hints. Byte caches retain the original URL and identity scope;
+public author lists reuse five-minute cache/single-flight lookups, with incomplete misses retryable.
+
+[BUD-10 at `b5bd280`](https://github.com/hzrd149/blossom/blob/b5bd2801d1763aa635fc8fea7a76597e0eb18990/buds/10.md)
+requires lowercase hashes and an extension (default `.bin`) for emitted references.
+Extensionless reads, mixed-case hashes, and the `sha256:` alias are deliberately
+retained local compatibility, not a full BUD-10 conformance claim. Upload URI
+generation is unchanged. Paja refuses redirects, verifies SHA-256 and byte MIME,
+and permits plain-HTTP
 transport only for configured loopback development defaults. Browser-only Paja
 cannot pin DNS results, so production runtimes must add the draft's DNS-time
 private-address checks. The current
 [NAP-RESOURCE draft at `fa6bcc6`](https://github.com/napplet/naps/blob/fa6bcc6935aa19e7b70ab2a2c721dafca77c78e1/naps/NAP-RESOURCE.md)
-assigns fetching and policy to the runtime and defines no wire-level Blossom
-server-hint field. Retaining verified manifest servers per window is therefore
-Paja host policy, informed by the current
+was rechecked for this MIME policy against PR #80's exact head. The opaque
+fallback preserves byte sniffing, hash verification, complete Blob delivery,
+ordered independent bulk results, and the prohibition on raw SVG delivery.
+This is bounded conformance, not full draft compliance: existing developer HTTP
+policy, DNS enforcement, SVG rejection instead of rasterization, and request
+server-hint differences remain outside this change. The draft defines no
+wire-level Blossom server-hint field. Retaining verified manifest servers per
+window is therefore Paja host policy, informed by the current
 [NIP-5D draft at `24711d9`](https://github.com/nostr-protocol/nips/blob/24711d9c47bbdd07908bf1d52bf677d9cbc530f0/5D.md),
 which defines manifest `server` tags. The existing request-server compatibility
 path comes from the earlier NAP-RESOURCE draft at `9511232`, with the merged package implementation
@@ -364,3 +473,13 @@ Full package docs: [`docs/packages/paja.md`](../../docs/packages/paja.md).
 Getting started: [`docs/how-tos/paja-getting-started.md`](../../docs/how-tos/paja-getting-started.md).
 Local authoring how-to: [`docs/how-tos/paja-local-authoring.md`](../../docs/how-tos/paja-local-authoring.md).
 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
+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).