@kehto/paja 0.32.0 → 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 +134 -55
- package/dist/browser-host.js +12829 -8644
- package/dist/browser-host.js.map +1 -1
- package/dist/{chunk-DDYBKY5L.js → chunk-ZAIBJIBA.js} +253 -9
- package/dist/chunk-ZAIBJIBA.js.map +1 -0
- package/dist/cli.d.ts +1 -1
- package/dist/cli.js +2 -4
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.js +1 -1
- package/dist/{server-bAe1oDUG.d.ts → server-B7uqpu8g.d.ts} +0 -6
- package/package.json +6 -6
- package/dist/chunk-DDYBKY5L.js.map +0 -1
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
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
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
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
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
|
|
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.
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
Paja
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
`
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
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
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
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
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
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
|
|
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
|
|