@kehto/paja 0.28.1 → 0.29.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
@@ -340,6 +340,12 @@ artifact CSP is retained. Set `frame-ancestors` on the host HTTP response, not
340
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
341
  Local target-URL authoring mode retains its separate development policy and HMR.
342
342
 
343
+ The Paja host page carries `Content-Security-Policy: frame-src 'none'` in its
344
+ `<head>` (`renderNappletFramePolicyMeta()` from `@kehto/shell`), so a napplet
345
+ cannot navigate its frame away from the verified `srcdoc` at any time,
346
+ including before its first `load`, which NIP-5D's replacement evidence cannot
347
+ observe. Paja refuses to load a napplet into a frame whose host page lacks it.
348
+
343
349
  Environment simulation can be supplied through CLI flags or a JSON config file:
344
350
 
345
351
  ```bash
@@ -602,6 +608,21 @@ This non-normative guidance defers to the living [NAP-LLM](https://github.com/na
602
608
 
603
609
  Paja MUST load all three NIP-5D manifest kinds: root `15129`, named `35129`, and snapshot `5129`. Use an `naddr` with an empty identifier for the latest root, an `naddr` with the literal `d` identifier for the latest named napplet, or a `nevent` to pin a signed event of any of the three kinds. Snapshots require `nevent` because they are immutable events without replaceable coordinates. All paths verify the signed manifest and artifact hash before injecting `srcdoc`. Distinct snapshots retain separate tabs and catalog identities even when their artifact bytes match.
604
610
 
611
+
612
+ ### Relay unreachable
613
+
614
+ Pointer resolution tracks each relay's connection outcome, not just whether
615
+ events arrived. When **zero** relays open a WebSocket, the resolver throws
616
+ `PajaRelayUnreachableError` (`code: 'relay-unreachable'`, with a
617
+ `PajaRelayConnectionSummary` of connected/failed/pending relays) instead of the
618
+ generic timeout, and the pointer status reads `No relay connection could be
619
+ opened … 0 of N relays connected …` with the likely causes: the browser is
620
+ offline, the relays are blocked, or the browser reached its WebSocket connection
621
+ limit (for example many open tabs each holding relay connections). Paja logs a
622
+ `paja.relay.unreachable` entry with the per-relay detail. A deadline expiry with
623
+ at least one live relay keeps the timeout message and now states how many relays
624
+ connected. Pools without `ensureRelay` keep the previous messages.
625
+
605
626
  ## Controller diagnostics
606
627
 
607
628
  Paja shows a numbered controller icon directly beside the console arrow for each controller the browser detects. Each slot has its own color and input animation; hover for the controller model and activity state. Buttons and stick movement light up only that controller (stick movement below 0.12 is ignored). Quick taps retain the highlight briefly so they are easy to spot. Reduced-motion settings keep the activity highlight without animation. Disconnecting removes the icon. Browsers may require a button press before exposing a newly connected controller. These host diagnostics work without a napplet gamepad subscription and do not change focus-scoped input delivery.
@@ -16749,6 +16749,10 @@ function postShellInit(windowId, environment) {
16749
16749
  };
16750
16750
  originRegistry.postToNapplet(windowId, initMsg);
16751
16751
  }
16752
+ var NAPPLET_FRAME_POLICY = "frame-src 'none'";
16753
+ function hasNappletFramePolicy(doc) {
16754
+ return [...doc.querySelectorAll('meta[http-equiv="Content-Security-Policy" i]')].some((meta) => meta.content.split(";").some((directive) => directive.trim() === NAPPLET_FRAME_POLICY));
16755
+ }
16752
16756
  var NAPPLET_HELLO = "napplet.hello";
16753
16757
  function reportUnrouted(hooks, event, reason) {
16754
16758
  if (!hooks.onUnroutedMessage) return;
@@ -16770,6 +16774,15 @@ var REVOCATION_DETAIL = {
16770
16774
  function isHello(data) {
16771
16775
  return typeof data === "object" && data !== null && data.type === NAPPLET_HELLO;
16772
16776
  }
16777
+ var framePolicyWarned = false;
16778
+ function warnWithoutFramePolicy(frame) {
16779
+ const doc = frame.ownerDocument;
16780
+ if (framePolicyWarned || !doc || hasNappletFramePolicy(doc)) return;
16781
+ framePolicyWarned = true;
16782
+ console.warn(
16783
+ `[kehto] The host page has no "${NAPPLET_FRAME_POLICY}" CSP. A napplet that navigates its frame before its first load is invisible to NIP-5D's replacement evidence; add renderNappletFramePolicyMeta() to the host page <head>.`
16784
+ );
16785
+ }
16773
16786
  function createNip5dTransport({ hooks, runtime, state: shellReadyState }) {
16774
16787
  const bindings = /* @__PURE__ */ new Map();
16775
16788
  function currentBinding(windowId) {
@@ -16872,6 +16885,7 @@ function createNip5dTransport({ hooks, runtime, state: shellReadyState }) {
16872
16885
  bindPort(windowId, sourceWindow, event.origin, ports[0]);
16873
16886
  }
16874
16887
  function observeFrame(frame, windowId) {
16888
+ warnWithoutFramePolicy(frame);
16875
16889
  let loads = 0;
16876
16890
  const onLoad = () => {
16877
16891
  loads += 1;
@@ -17155,9 +17169,20 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
17155
17169
  const target = window;
17156
17170
  const allowed2 = new Set(domains);
17157
17171
  const requestTimeoutMs = 3e4;
17158
- for (const rtcCtor of ["RTCPeerConnection", "webkitRTCPeerConnection"]) {
17172
+ const rtcGlobals = /* @__PURE__ */ new Set([
17173
+ "webkitRTCPeerConnection",
17174
+ "mozRTCPeerConnection",
17175
+ "webkitRTCSessionDescription",
17176
+ "mozRTCSessionDescription",
17177
+ "webkitRTCIceCandidate",
17178
+ "mozRTCIceCandidate"
17179
+ ]);
17180
+ for (const key of Object.getOwnPropertyNames(target)) {
17181
+ if (key.startsWith("RTC")) rtcGlobals.add(key);
17182
+ }
17183
+ for (const rtcName of rtcGlobals) {
17159
17184
  try {
17160
- Object.defineProperty(target, rtcCtor, {
17185
+ Object.defineProperty(target, rtcName, {
17161
17186
  value: void 0,
17162
17187
  writable: false,
17163
17188
  configurable: false,
@@ -25115,6 +25140,9 @@ function ensureFreshNappletFrame(frame) {
25115
25140
  }
25116
25141
  async function navigateFrame(frame, config, generation2, adapter, resolvedTarget, windowId, isCurrent, onRegistered) {
25117
25142
  denyNappletControllerAccess(frame);
25143
+ if (!hasNappletFramePolicy(frame.ownerDocument)) {
25144
+ throw new Error("[paja] The host page has no frame-src lock; refusing to load a napplet whose frame could navigate away from its verified document.");
25145
+ }
25118
25146
  const identity = getTargetOriginIdentity(config, resolvedTarget);
25119
25147
  const environment = resolvePajaFrameEnvironment(adapter, identity);
25120
25148
  const domains = environment.capabilities.domains;
@@ -27097,6 +27125,16 @@ function freezeRecord(record3) {
27097
27125
 
27098
27126
  // src/runtime-resolver.ts
27099
27127
  var PAJA_NAPPLET_MANIFEST_KINDS = NAPPLET_KINDS;
27128
+ var PajaRelayUnreachableError = class extends Error {
27129
+ constructor(message3, connections) {
27130
+ super(message3);
27131
+ this.connections = connections;
27132
+ this.name = "PajaRelayUnreachableError";
27133
+ }
27134
+ connections;
27135
+ /** Stable discriminator for hosts that cannot rely on `instanceof` across bundles. */
27136
+ code = "relay-unreachable";
27137
+ };
27100
27138
  function decodePajaPointer(value) {
27101
27139
  const trimmed = value.trim();
27102
27140
  const decoded = decode(trimmed);
@@ -27178,9 +27216,17 @@ async function resolvePointerEvent(pointer, pool, relays, maxWaitMs) {
27178
27216
  const result2 = await queryPointerRelays(pool, relays, filter, maxWaitMs);
27179
27217
  const event = result2.events.filter((candidate) => matchesPointer(pointer, candidate)).sort((a, b) => b.created_at - a.created_at || a.id.localeCompare(b.id))[0];
27180
27218
  if (!event) {
27219
+ const connections = result2.connections;
27220
+ if (connections && connections.total > 0 && connections.connected.length === 0) {
27221
+ throw new PajaRelayUnreachableError(
27222
+ describeRelayUnreachable(pointer.type, connections, maxWaitMs),
27223
+ connections
27224
+ );
27225
+ }
27181
27226
  if (result2.timedOut) {
27227
+ const connectedNote = connections ? ` (${connections.connected.length} of ${connections.total} relays connected)` : "";
27182
27228
  throw new Error(
27183
- `Relay resolution timed out after ${maxWaitMs}ms for ${pointer.type} pointer across ${relays.length} relays before complete EOSE.`
27229
+ `Relay resolution timed out after ${maxWaitMs}ms for ${pointer.type} pointer across ${relays.length} relays before complete EOSE${connectedNote}.`
27184
27230
  );
27185
27231
  }
27186
27232
  const failures = relayFailureReasons(result2.reasons);
@@ -27197,11 +27243,55 @@ async function resolvePointerEvent(pointer, pool, relays, maxWaitMs) {
27197
27243
  }
27198
27244
  return event;
27199
27245
  }
27200
- function queryPointerRelays(pool, relays, filter, maxWaitMs) {
27201
- if (pool.subscribeManyEose) {
27202
- return queryPointerRelaySubscription(pool, relays, filter, maxWaitMs);
27246
+ async function queryPointerRelays(pool, relays, filter, maxWaitMs) {
27247
+ const tracker = trackRelayConnections(pool, relays, maxWaitMs);
27248
+ const result2 = pool.subscribeManyEose ? await queryPointerRelaySubscription(pool, relays, filter, maxWaitMs) : await queryPointerRelaySync(pool, relays, filter, maxWaitMs);
27249
+ return tracker ? { ...result2, connections: tracker.snapshot() } : result2;
27250
+ }
27251
+ function trackRelayConnections(pool, relays, maxWaitMs) {
27252
+ const ensureRelay = pool.ensureRelay?.bind(pool);
27253
+ if (!ensureRelay) return null;
27254
+ const urls = [...new Set(relays)];
27255
+ const connected = [];
27256
+ const failed2 = [];
27257
+ const pending = new Set(urls);
27258
+ for (const url of urls) {
27259
+ const settle7 = (outcome, reason) => {
27260
+ if (!pending.delete(url)) return;
27261
+ if (outcome === "connected") connected.push(url);
27262
+ else failed2.push({ url, reason: reason ?? "connection failed" });
27263
+ };
27264
+ try {
27265
+ ensureRelay(url, { connectionTimeout: maxWaitMs }).then(
27266
+ () => settle7("connected"),
27267
+ (error) => settle7("failed", describeRelayFailure(error))
27268
+ );
27269
+ } catch (error) {
27270
+ settle7("failed", describeRelayFailure(error));
27271
+ }
27203
27272
  }
27204
- return queryPointerRelaySync(pool, relays, filter, maxWaitMs);
27273
+ return {
27274
+ snapshot: () => ({
27275
+ total: urls.length,
27276
+ connected: [...connected],
27277
+ failed: [...failed2],
27278
+ pending: [...pending]
27279
+ })
27280
+ };
27281
+ }
27282
+ function describeRelayFailure(error) {
27283
+ const text2 = error instanceof Error ? error.message : String(error ?? "");
27284
+ const trimmed = text2.trim();
27285
+ return (trimmed.length > 0 ? trimmed : "connection failed").slice(0, 160);
27286
+ }
27287
+ function describeRelayUnreachable(pointerType, connections, maxWaitMs) {
27288
+ const reasons = relayFailureReasons(connections.failed.map((entry) => entry.reason));
27289
+ const parts = [
27290
+ `No relay connection could be opened for the ${pointerType} pointer: 0 of ${connections.total} relays connected within ${maxWaitMs}ms (${connections.failed.length} failed, ${connections.pending.length} still connecting).`,
27291
+ "The browser is offline, the relays are blocked, or the browser reached its WebSocket connection limit (for example many open tabs each holding relay connections) \u2014 close some tabs and retry."
27292
+ ];
27293
+ if (reasons.length > 0) parts.push(`Relay errors: ${reasons.join("; ")}.`);
27294
+ return parts.join(" ");
27205
27295
  }
27206
27296
  function queryPointerRelaySubscription(pool, relays, filter, maxWaitMs) {
27207
27297
  return new Promise((resolve) => {
@@ -29338,6 +29428,17 @@ async function loadRuntimePointer(state, context, value, options = {}) {
29338
29428
  state.resolvedTarget = null;
29339
29429
  setPointerStatus(state, message3);
29340
29430
  setStatus(state, "error");
29431
+ if (error instanceof PajaRelayUnreachableError) {
29432
+ const { total, connected, failed: failed2, pending } = error.connections;
29433
+ appendPajaMessageLog(state, "paja", {
29434
+ type: "paja.relay.unreachable",
29435
+ relays: total,
29436
+ connected: connected.length,
29437
+ failed: failed2.map((entry) => `${entry.url}: ${entry.reason}`),
29438
+ pending: [...pending],
29439
+ hint: "browser offline, relays blocked, or WebSocket connection limit reached \u2014 close other tabs holding relay connections and retry"
29440
+ });
29441
+ }
29341
29442
  appendPajaMessageLog(state, "paja", { type: "paja.pointer.error", error: message3 });
29342
29443
  }
29343
29444
  }