@kehto/paja 0.32.1 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -70,7 +70,7 @@ usable; collapsing never reloads the running app or discards unsaved drafts.
70
70
 
71
71
  The console shows supported interfaces with per-domain injection toggles
72
72
  (green when ready, yellow `⚠` when advertised but unconfigured, red when disabled),
73
- runtime ACL controls, signer controls, and a filterable message log with visible
73
+ runtime ACL controls, Firewall permissions, signer controls, and a filterable message log with visible
74
74
  error details. It starts expanded and collapses to the left with the chevron
75
75
  button in the top bar; the same button brings the whole panel back. The toolbar
76
76
  stays onscreen after restoring a saved collapsed preference, including when no
@@ -84,6 +84,10 @@ available, can connect to a bunker/NIP-46 URI, and only uses the generated local
84
84
  development signer when the Dev signer button is selected. Sign, publish, DM
85
85
  send, filesystem picker, Blossom upload, and external-link requests use one serialized in-page
86
86
  confirmation dialog. Deny has initial focus and Escape denies. A napplet-scoped
87
+ serial or BLE chooser receives runtime approval first; Paja then keeps the
88
+ selected device host-private until a second approval permits opening the port or
89
+ GATT connection. Source-owned device sessions close and stop delivery when that
90
+ authority is revoked. A napplet-scoped
87
91
  sign or publish request defaults to one-time approval. The modal can remember
88
92
  one event kind, all events for the current action, or **all signing and publishing
89
93
  from this napplet version**. Signing-only permission never implies publication;
@@ -107,6 +111,13 @@ module lifetime; current records stay quiet. Removing a window or changing the
107
111
  signer denies pending signing/publication. Link requests always use the modal,
108
112
  and the external browser handoff runs directly from its approval click with
109
113
  `noopener,noreferrer`. Other operation permissions remain separate.
114
+ The remembered choices are a legacy confirmation preference only: every sign
115
+ request must first pass the runtime Firewall operation approval for its current
116
+ verified source and exact scope. Actual legacy use warns once per page with
117
+ `FW-PAJA-SIGNER-CONSENT-LEGACY-001`; use Firewall grants instead. The Firewall
118
+ permissions panel shows live grants, revocation, clear, and storage retry.
119
+ Without browser storage only session/once decisions are offered; failed durable
120
+ saves block new grants.
110
121
  This is Paja host policy under [NAP-RELAY PR #2 at `9f30b350`](https://github.com/napplet/naps/blob/9f30b3505335a52c574ff570576687d6467021ff/naps/NAP-RELAY.md),
111
122
  [NAP-OUTBOX PR #32 at `8865f73d`](https://github.com/napplet/naps/blob/8865f73d52a4864afee145f28d26520476273927/naps/NAP-OUTBOX.md)
112
123
  and [NAP-LINK PR #53 at `50a2cd45`](https://github.com/napplet/naps/blob/50a2cd45e76f06e87b87e93842badf4c61f17bde/naps/NAP-LINK.md), rather than
@@ -185,6 +196,13 @@ controller. DM also requires the Dev signer and live relays; FS requires a
185
196
  successful OPFS probe, while picker calls additionally require the corresponding
186
197
  browser API and a host-owned approval click. Missing host boundaries remove
187
198
  those domains from `shell.init`.
199
+ For `notify`, Paja renders attributed text without fetching icons. The shared
200
+ Firewall approves the exact notification operation/channel before the browser
201
+ effect; Paja's own permission cache is tied to the current verified app artifact.
202
+ Window teardown or revocation clears the UI and invalidates pending answers.
203
+ For `link.open`, Paja approves the exact HTTP(S) URL and rechecks the approval
204
+ signal and verified artifact after host confirmation before navigation. It
205
+ opens external links with `noopener,noreferrer`.
188
206
  Live relay URLs are validated before advertisement, fixture events and local
189
207
  publish echoes never enter live reads, and relay event sidecars disclose only
190
208
  sources that the relay pool actually observed.
@@ -312,14 +330,32 @@ Paja activates delivered handler tabs because its stage shows one tab at a time.
312
330
  `behavior.focus` is advisory; `reuse: false` creates a new surface. Existing caller
313
331
  tabs remain open. Installed contracts and domains appear in pointer diagnostics.
314
332
 
333
+ The Paja CLI starts the package server, which renders the same host page used by
334
+ the static runtime. Both load `browser-host.js`; its single-window, tab, local
335
+ file, and verified-pointer routes all pass executable HTML through
336
+ `admitBrowserDocument`. There is no separate bench app or second executable
337
+ iframe loader in this repository.
338
+
315
339
  Kehto provides the optional `window.napplet.shell` interface for environment information. Other domains route through trusted iframe creation identity independently of readiness. `supports(domain)` queries namespace presence locally. See the living [NAP-SHELL](https://github.com/napplet/naps/blob/master/naps/NAP-SHELL.md).
316
340
 
317
- Before Paja assigns a verified runtime-pointer document to `srcdoc`, it calls
318
- `@kehto/shell`'s `prepareNappletSrcdoc`. The shell inserts validated CSP first,
319
- then the mandatory namespace. Defaults permit inline script/style, WASM byte
320
- compilation, `data:`/`blob:` images and `data:` fonts, and deny other resource
321
- classes. Paja grants direct connections only to resolved relay and Blossom
322
- origins plus explicit host grants.
341
+ Before Paja assigns verified pointer or development bytes to `srcdoc`, it uses
342
+ `admitBrowserDocument` to approve the declared interfaces and any explicit
343
+ direct browser origins. Required denial blocks launch; optional denial narrows
344
+ the injected namespace and later shell environment. The host registers the
345
+ trusted source before the approved document executes. The injected CSP defaults
346
+ to closed remote source lists. Relay and Blossom discovery hints select mediated
347
+ services only and never grant the iframe direct browser traffic.
348
+
349
+ Unsigned development HTML can request interfaces with space-separated
350
+ `<meta name="napplet-requires" content="shell relay">` and
351
+ `<meta name="napplet-optional" content="media">` declarations. They request
352
+ approval; they do not grant it. Paja binds each development grant to the exact
353
+ target URL and fetched HTML hash, so editing the document requires a new
354
+ approval. A live dev server uses directive-specific browser source approval
355
+ for its script, style, image, font, worker, media, and connection sources. Its
356
+ frame cannot receive `resource`; declare `resource` only for a self-contained
357
+ local HTML file with no remote sources. When no development declarations exist,
358
+ Paja offers available interfaces as optional for the current session.
323
359
 
324
360
  Hosts can pass `csp` to `createPajaRuntimeHostConfig`:
325
361
 
@@ -328,17 +364,19 @@ const config = createPajaRuntimeHostConfig({
328
364
  pointer,
329
365
  csp: {
330
366
  connectOrigins: ['https://api.example'],
331
- directives: { 'media-src': ['blob:'], 'img-src': ['data:'] },
332
367
  },
333
368
  });
334
369
  ```
335
370
 
336
- The shell rejects broad JavaScript evaluation, non-origin connection grants,
337
- and script policies that block its bootstrap. NIP-5D's CSP recommendations are
338
- enforced; individual baseline source lists remain configurable. Existing
339
- artifact CSP is retained. Set `frame-ancestors` on the host HTTP response, not
340
- 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).
341
- Local target-URL authoring mode retains its separate development policy and HMR.
371
+ Each explicit origin is a separate network approval. Supported `csp.directives`
372
+ entries are reduced to exact origins for their named source directive and require
373
+ the same approval; unsupported directives and broad source expressions fail
374
+ closed. Browser sources follow CSP scheme/port matching, including HTTP to
375
+ HTTPS upgrades; they are not literal origin-equality checks. The approval UI
376
+ discloses this when relevant. The shared CSP still denies frames, objects,
377
+ manifests, and unlisted sources.
378
+ Set `frame-ancestors` on the host HTTP response, not in a meta policy. See the
379
+ [shared policy contract](https://github.com/kehto/web/blob/main/docs/policies/NIP-5D-CONFORMANCE.md#shell-csp-enforcement).
342
380
 
343
381
  The Paja host page carries `Content-Security-Policy: frame-src 'none'` in its
344
382
  `<head>` (`renderNappletFramePolicyMeta()` from `@kehto/shell`), so a napplet
@@ -348,6 +386,11 @@ observe. Paja refuses to load a napplet into a frame whose host page lacks it.
348
386
 
349
387
  Environment simulation can be supplied through CLI flags or a JSON config file:
350
388
 
389
+ The old `--firewall-mode` and `simulation.firewall` settings are rejected because
390
+ they never granted a scoped permission. Use the Firewall approvals panel for
391
+ interface, resource, and network decisions. Simulation settings can still
392
+ restrict availability or select test backends, but cannot approve a target.
393
+
351
394
  ```bash
352
395
  kehto paja \
353
396
  --target-url http://127.0.0.1:5173 \
@@ -404,6 +447,15 @@ use HTTPS; plain HTTP is accepted only for loopback development hosts. The
404
447
  server must allow Paja's browser origin, `PUT` and `OPTIONS`, plus the
405
448
  `Authorization` and `Content-Type` CORS headers.
406
449
 
450
+ With runtime permissions enabled, Paja first prepares the selected Blossom
451
+ `/upload` endpoint and signer identity without prompting, signing, or sending
452
+ bytes. Firewall then approves the exact upload resource (including byte digest,
453
+ size and media details) together with the selected network origin. Paja's
454
+ confirmation and Blossom signing run only inside that approved lifetime.
455
+ Revocation or signer replacement aborts the upload and suppresses later status
456
+ updates. A returned public CDN URL is result metadata; it does not grant the
457
+ napplet direct network access to that URL.
458
+
407
459
  Explicit servers win. With no explicit server, Paja may use an independently
408
460
  warmed snapshot of the active signer's newest BUD-03 kind `10063` `server`
409
461
  tags. `upload.info` and `upload.upload` never initiate that discovery. Pointer
@@ -432,22 +484,39 @@ Valid saves apply to subsequent Blossom requests across all running tabs,
432
484
  without reloading their frames. The list persists in the host origin's
433
485
  `localStorage`; if storage fails, it remains usable **session-only**, and the
434
486
  status warns that an older saved list may return after reload. Extras are
435
- appended after existing request/event/user/window/configured defaults. The
487
+ appended after existing URI/event/user/window/configured defaults. The
436
488
  combined eight-server cap remains: extras may not be reached if earlier
437
489
  candidates fill it. This setting does not change upload destinations,
438
490
  per-napplet NAP-CONFIG, initial pointer/artifact loading, direct HTTP(S) resource
439
- URLs, or napplet CSP/network grants. Browser CORS and the DNS limitation below
440
- still apply.
441
-
442
- Paja's developer-runtime policy accepts arbitrary `http:` and `https:` resource
443
- URLs so a normal remote image does not look broken merely because its origin was
444
- not pre-granted. Paja resolves those URLs with browser `fetch`, omits credentials
445
- and referrer data, caps responses at 10 MiB, and classifies MIME from returned
446
- bytes. Its byte classifier recognizes checksum-valid Game Boy ROM headers as
447
- `application/vnd.nintendo.gb-rom`; it never trusts a server-supplied media type.
448
- Browser network and CORS rules still apply: an unreadable response is the
449
- canonical `network-error`. HTTP(S) and locally decoded `data:` bytes must have a
450
- recognized type; opaque invalid-UTF-8 or NUL-bearing binary remains rejected.
491
+ URLs, or napplet CSP/network grants. Each actual HTTP(S) destination still
492
+ requires authorization and must pass the proxy address policy below.
493
+
494
+ Paja redirects HTML requests using an alias hostname to its configured host
495
+ origin before issuing the proxy capability cookie. Resource proxy requests
496
+ remain restricted to that canonical origin.
497
+
498
+ Paja resolves HTTP(S) resources through its protected, same-origin
499
+ `POST /__kehto/resource` endpoint. The resource request and each actual network
500
+ destination have separate authorization requirements; an interface grant or
501
+ Blossom server hint grants neither. The resolver requires the request-bound
502
+ network authorization callback and refuses network access when it is absent.
503
+ The proxy validates its host, main-frame Origin, JSON POST, and server-instance
504
+ HttpOnly cookie before DNS. It pins a permitted public address to the connection,
505
+ preserves TLS hostname checks, omits upstream credentials/referrer, and bounds
506
+ responses to 10 MiB and 30 seconds. Private, loopback, and other blocked
507
+ special-purpose addresses are rejected, including development loopback targets.
508
+
509
+ Redirects return metadata to the trusted resolver instead of redirecting the
510
+ browser. The resolver permits at most five hops, authorizes each destination,
511
+ and repeats the proxy's DNS/address checks. Cancelling the host request aborts
512
+ upstream work. Remote resource responses no longer depend on allowing the opaque
513
+ iframe origin through upstream CORS. See the [resource proxy policy](../../docs/policies/RESOURCE-PROXY.md)
514
+ for caller checks, address policy, deadlines, and regression coverage.
515
+
516
+ Paja classifies returned bytes itself. Its classifier recognizes checksum-valid
517
+ Game Boy ROM headers as `application/vnd.nintendo.gb-rom`; upstream media types
518
+ never establish the result MIME. HTTP(S) and locally decoded `data:` bytes must
519
+ have a recognized type; opaque invalid-UTF-8 or NUL-bearing binary remains rejected.
451
520
  Only capped, SHA-256-verified canonical Blossom resources may return unknown
452
521
  opaque bytes as `application/octet-stream`. Recognized formats retain their
453
522
  sniffed MIME. SVG, HTML, XML and script prefixes remain blocked, even with NUL or
@@ -472,13 +541,18 @@ invalid/private literals, and deduplicates them. Unlike BUD-10's suggested HTTP
472
541
  retry, URI hints never enable public HTTP. For a Blossom URL
473
542
  previously returned to the same napplet window by `outbox.getEvent`,
474
543
  `outbox.query`, or `outbox.subscribe`, Paja retains bounded event context
475
- without prefetching bytes. Resolution tries explicit request servers, URI `xs`,
476
- and event-local server hints first, then lazily queries URI `as`, event-hinted authors' and the
477
- event publisher's newest BUD-03 kind `10063` lists through the verified
478
- NIP-65-aware OUTBOX router, then queries the active shell user's BUD-03 list
479
- through that same router, then uses the current window's verified
480
- pointer-manifest servers, followed by upload-runtime fallbacks and saved extra
481
- resource servers. The user-list
544
+ without prefetching bytes. Resolution tries URI `xs` and event-local server hints first, then lazily queries URI `as`, event-hinted authors' and the
545
+ event publisher's newest BUD-03 kind `10063` lists through host-configured
546
+ NIP-65 bootstrap relays and the selected author relay, then queries the active
547
+ shell user's BUD-03 list through the same approval-bound relay path, then uses
548
+ the current window's verified pointer-manifest servers, followed by upload-runtime
549
+ fallbacks and saved extra resource servers. Every bootstrap and author relay is
550
+ authorized as its exact `ws:`/`wss:` destination before its socket opens. The
551
+ host refreshes signer-derived bootstrap URLs only at signer initialization or a
552
+ signer lifecycle change; a resource request reads that bounded host cache and
553
+ never calls an external signer's `getRelays()` hook, because that hook can
554
+ perform opaque extension work before an origin exists to approve. If refreshing
555
+ the cache fails, configured host bootstrap relays remain available. The user-list
482
556
  lookup works independently of upload mode; an upload runtime may reuse the same
483
557
  servers when present. ROM-specific event and publisher locations retain
484
558
  priority over the user/runtime fallbacks. URI length is capped at 8192 characters;
@@ -499,26 +573,31 @@ public author lists reuse five-minute cache/single-flight lookups, with incomple
499
573
  requires lowercase hashes and an extension (default `.bin`) for emitted references.
500
574
  Extensionless reads, mixed-case hashes, and the `sha256:` alias are deliberately
501
575
  retained local compatibility, not a full BUD-10 conformance claim. Upload URI
502
- generation is unchanged. Paja refuses redirects, verifies SHA-256 and byte MIME,
503
- and permits plain-HTTP
504
- transport only for configured loopback development defaults. Browser-only Paja
505
- cannot pin DNS results, so production runtimes must add the draft's DNS-time
506
- private-address checks. The current
507
- [NAP-RESOURCE draft at `fa6bcc6`](https://github.com/napplet/naps/blob/fa6bcc6935aa19e7b70ab2a2c721dafca77c78e1/naps/NAP-RESOURCE.md)
508
- was rechecked for this MIME policy against PR #80's exact head. The opaque
509
- fallback preserves byte sniffing, hash verification, complete Blob delivery,
510
- ordered independent bulk results, and the prohibition on raw SVG delivery.
511
- This is bounded conformance, not full draft compliance: existing developer HTTP
512
- policy, DNS enforcement, SVG rejection instead of rasterization, and request
513
- server-hint differences remain outside this change. The draft defines no
514
- wire-level Blossom server-hint field. Retaining verified manifest servers per
515
- window is therefore Paja host policy, informed by the current
516
- [NIP-5D draft at `24711d9`](https://github.com/nostr-protocol/nips/blob/24711d9c47bbdd07908bf1d52bf677d9cbc530f0/5D.md),
517
- which defines manifest `server` tags. The existing request-server compatibility
518
- path comes from the earlier NAP-RESOURCE draft at `9511232`, with the merged package implementation
519
- [`napplet/web#206@19e0029b`](https://github.com/napplet/web/pull/206) released as
520
- `@napplet/core`/`@napplet/nap` 0.32.0, `@napplet/shim` 0.30.0, and
521
- `@napplet/sdk` 0.28.0. Publisher discovery follows
576
+ generation is unchanged. Paja verifies SHA-256 and byte MIME after authorized
577
+ proxy retrieval. The checked [NAP-RESOURCE draft at `ae5b9c6`](https://github.com/napplet/naps/blob/ae5b9c64ab8a4d8909f288829a01e99d6bd713bc/naps/NAP-RESOURCE.md)
578
+ uses canonical `id` correlation, a single `url` or ordered `urls` list, and padded
579
+ RFC 4648 base64 wire bytes. The injected web API converts verified wire bytes to
580
+ `Blob` values; a JavaScript `Blob` is not the wire payload. Per-item bulk outcomes
581
+ preserve input order. The old `requestId` input, object-form `requests` list, and
582
+ wire-level `servers` hint have been retired from this contract. Use URI hints or
583
+ host-owned resolver configuration for Blossom discovery. See
584
+ [`RESOURCE_FIELDS` in the compatibility register](../../docs/compatibility.md).
585
+
586
+ Verified manifest servers remain source-scoped Paja host policy under the
587
+ [NIP-5D draft at `5560820`](https://github.com/dskvr/nips/blob/5560820fa4f37f45b8ab742a11aeb3001b17dc67/5D.md).
588
+ Neither those hints nor stored extra servers grant iframe network authority.
589
+
590
+ The shared launch admission and CSP isolate mediated `resource` frames from
591
+ direct browser traffic. NAP-RESOURCE requires direct-network denial before exposing `resource`, including
592
+ remote script, image, style, font, and worker paths as well as `connect-src`.
593
+ The proxy and service approval checks alone do not stop a frame with permissive
594
+ CSP from contacting remote servers. Explicit direct-network frames use the
595
+ compatible interface set defined by that host policy; required interfaces cannot
596
+ be silently dropped. Paja's host-injected base URL is limited to the exact
597
+ approved development origin so relative assets resolve. SVG rejection rather
598
+ than rasterization and the retained
599
+ Blossom URI aliases are also bounded host behavior, not a claim of complete draft
600
+ conformance. Publisher discovery follows
522
601
  [Blossom BUD-03 at `b5bd280`](https://github.com/hzrd149/blossom/blob/b5bd2801d1763aa635fc8fea7a76597e0eb18990/buds/03.md).
523
602
 
524
603
  Full package docs: [`docs/packages/paja.md`](../../docs/packages/paja.md).
@@ -598,7 +677,7 @@ remain a documented upstream spec gap; no host sender identity is invented.
598
677
 
599
678
  ## GAMEPAD integration
600
679
 
601
- This non-normative guidance defers to the living [NAP-GAMEPAD](https://github.com/napplet/naps/pull/108). Services export `createGamepadService` and `browserGamepadOptions`; shell exports `denyNappletControllerAccess`. Paja registers one host reader and deny native gamepad/HID/USB paths before frame execution. Source-bound subscriptions receive immediate full snapshots; only the visible host's input owner gets live controls. Focus loss supplies neutral controls and timestamp zero; unsubscribe, window destruction, and service removal release polling. Non-browser or denied native readers report the proposal's unavailable reasons. See [Controller input](https://github.com/kehto/web/blob/main/docs/gamepad.md).
680
+ This non-normative guidance defers to [NAP-GAMEPAD at `napplet/naps@19de5ce1`](https://github.com/napplet/naps/blob/19de5ce1cea40cd4c76089cdd8126e9f87648049/naps/NAP-GAMEPAD.md). Services export `createGamepadService` and `browserGamepadOptions`; shell exports `denyNappletControllerAccess`. Paja registers one host reader and denies native gamepad/HID/USB paths before frame execution. A subscription must approve the host-private `gamepad:input` resource before the reader starts; denial emits `reason: "blocked"`. Only the visible host's input owner receives live controls. Focus loss supplies neutral controls and timestamp zero; unsubscribe, revocation, window destruction, and service removal release polling. See [Controller input](https://github.com/kehto/web/blob/main/docs/gamepad.md).
602
681
 
603
682
  ## LLM integration
604
683