@kehto/shell 0.27.0 → 0.28.1

package/README.md

@@ -126,6 +126,16 @@ survives same-frame navigation, but the port lives only in the verified document
   demand.
 - `ShellBridge.observeFrame(frame, windowId)` watches for the second load. Call
   it after the frame is in the DOM and before assigning `srcdoc`.
+- Load counting cannot see a napplet that navigates its frame before its own
+  first `load`: only the replacement fires `load`, and browsers fire no
+  MessagePort `close` event. Lock the frame instead: put
+  `renderNappletFramePolicyMeta()` (`Content-Security-Policy: frame-src 'none'`,
+  exported as `NAPPLET_FRAME_POLICY`) in the host page `<head>`, or send the
+  equivalent HTTP header. Browsers check every navigation of a child frame
+  against the embedding page's `frame-src`, including one the frame starts
+  itself, while an unfetched `srcdoc` still loads. `hasNappletFramePolicy(document)`
+  reports whether the meta element is present, and `observeFrame` warns once
+  when it is not. This is host page policy, not napplet protocol surface.
 - `originRegistry.register()` throws for a `Window` that already handed over (or
   lost) its port. Create a fresh iframe for every reload or navigation.
 - `ShellAdapter.onNappletMessage(windowId, message)` observes each port envelope

package/dist/index.d.ts

@@ -932,6 +932,42 @@ interface NappletSrcdocOptions extends NappletNamespacePreludeOptions {
  */
 declare function prepareNappletSrcdoc(html: string, options: NappletSrcdocOptions): string;
 
+/**
+ * @kehto/shell -- the embedding-page policy that keeps a napplet frame on its verified document.
+ *
+ * NIP-5D treats a second `load`, a second `napplet.hello` or the port closing as evidence that the verified document
+ * was replaced. None of these can observe a napplet that navigates its frame before its own first `load`: only the
+ * replacement fires `load`, and browsers fire no MessagePort `close` event. CSP checks every navigation of a child
+ * frame against the embedding page's `frame-src`, including one the frame starts itself, while an unfetched `srcdoc`
+ * document still loads. Setting this policy on the host page therefore blocks the replacement outright.
+ * This is host page policy, not napplet protocol surface: https://github.com/nostr-protocol/nips/pull/2303
+ */
+/** The `frame-src` directive a host page sets so napplet frames cannot navigate away from their `srcdoc`. */
+declare const NAPPLET_FRAME_POLICY = "frame-src 'none'";
+/**
+ * Render the host-page `<meta>` element carrying {@link NAPPLET_FRAME_POLICY}. Place it in the host page's `<head>`;
+ * a `meta` CSP outside `<head>` is ignored. An equivalent HTTP `Content-Security-Policy` header works too.
+ *
+ * @returns The meta element HTML
+ * @example
+ * ```ts
+ * const head = `<head>${renderNappletFramePolicyMeta()}</head>`;
+ * ```
+ */
+declare function renderNappletFramePolicyMeta(): string;
+/**
+ * Whether a host document carries {@link NAPPLET_FRAME_POLICY} in a `<meta>` CSP. A policy delivered only as an HTTP
+ * header is not visible here.
+ *
+ * @param doc - The host page document
+ * @returns True when a CSP meta element contains the directive
+ * @example
+ * ```ts
+ * if (!hasNappletFramePolicy(document)) throw new Error('napplet frames are not navigation-locked');
+ * ```
+ */
+declare function hasNappletFramePolicy(doc: Pick<Document, 'querySelectorAll'>): boolean;
+
 /**
  * Manifest cache — persists verified NIP-5A aggregate hashes per napplet identity.
  */
@@ -1764,4 +1800,4 @@ type ResourceInbound = ResourceInfoRequest | ResourceBytesRequest | ResourceByte
  */
 type ResourceOutbound = ResourceInfoResult | ResourceInfoError | ResourceBytesResult | ResourceBytesError | ResourceBytesManyResult | ResourceBytesManyError;
 
-export { type AclCheckEvent, type AclEntry, type AclStore, type AudioManager, type AudioSource, type AuthHooks, type BleHooks, type BrowserDeps, type CapabilityHooks, type CommonHooks, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type IntentHooks, type KeysProxy, type KeysProxyDeps, type LinkHooks, type ListsHooks, type LlmHooks, type ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, NAPPLET_HELLO, type NappletCspDirective, type NappletCspDirectives, type NappletCspOptions, type NappletMessageTarget, type NappletNamespacePreludeOptions, type NappletRevocation, type NappletRevocationReason, type NappletSrcdocOptions, type NormalizedIntentUri, type NotifyProxy, type NotifyProxyDeps, type OriginIdentity, type OriginRegistry, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesManyError, type ResourceBytesManyItem, type ResourceBytesManyRequest, type ResourceBytesManyResult, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceInfoError, type ResourceInfoRequest, type ResourceInfoResult, type ResourceOutbound, type ResourceRequestId, type SerialHooks, type SessionRegistry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ShellDomainState, type ShellEnvironment, type ThemeProxy, type ThemeProxyDeps, type UnroutedMessageInfo, type UploadBackendLike, type UploadHooks, type WebrtcHooks, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildNappletCsp, buildShellCapabilities, createIdentityProxy, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, denyNappletControllerAccess, getShellDomainState, injectNappletCsp, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, normalizeIntentUri, originRegistry, prepareNappletSrcdoc, renderNappletCspMeta, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };
+export { type AclCheckEvent, type AclEntry, type AclStore, type AudioManager, type AudioSource, type AuthHooks, type BleHooks, type BrowserDeps, type CapabilityHooks, type CommonHooks, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type IntentHooks, type KeysProxy, type KeysProxyDeps, type LinkHooks, type ListsHooks, type LlmHooks, type ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, NAPPLET_FRAME_POLICY, NAPPLET_HELLO, type NappletCspDirective, type NappletCspDirectives, type NappletCspOptions, type NappletMessageTarget, type NappletNamespacePreludeOptions, type NappletRevocation, type NappletRevocationReason, type NappletSrcdocOptions, type NormalizedIntentUri, type NotifyProxy, type NotifyProxyDeps, type OriginIdentity, type OriginRegistry, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesManyError, type ResourceBytesManyItem, type ResourceBytesManyRequest, type ResourceBytesManyResult, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceInfoError, type ResourceInfoRequest, type ResourceInfoResult, type ResourceOutbound, type ResourceRequestId, type SerialHooks, type SessionRegistry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ShellDomainState, type ShellEnvironment, type ThemeProxy, type ThemeProxyDeps, type UnroutedMessageInfo, type UploadBackendLike, type UploadHooks, type WebrtcHooks, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildNappletCsp, buildShellCapabilities, createIdentityProxy, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, denyNappletControllerAccess, getShellDomainState, hasNappletFramePolicy, injectNappletCsp, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, normalizeIntentUri, originRegistry, prepareNappletSrcdoc, renderNappletCspMeta, renderNappletFramePolicyMeta, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };

package/dist/index.js

@@ -1280,6 +1280,15 @@ function postShellInit(windowId, environment) {
   originRegistry.postToNapplet(windowId, initMsg);
 }
 
+// src/frame-policy.ts
+var NAPPLET_FRAME_POLICY = "frame-src 'none'";
+function renderNappletFramePolicyMeta() {
+  return `<meta http-equiv="Content-Security-Policy" content="${NAPPLET_FRAME_POLICY}">`;
+}
+function hasNappletFramePolicy(doc) {
+  return [...doc.querySelectorAll('meta[http-equiv="Content-Security-Policy" i]')].some((meta) => meta.content.split(";").some((directive) => directive.trim() === NAPPLET_FRAME_POLICY));
+}
+
 // src/nip5d-transport.ts
 var NAPPLET_HELLO = "napplet.hello";
 function reportUnrouted(hooks, event, reason) {
@@ -1302,6 +1311,15 @@ var REVOCATION_DETAIL = {
 function isHello(data) {
   return typeof data === "object" && data !== null && data.type === NAPPLET_HELLO;
 }
+var framePolicyWarned = false;
+function warnWithoutFramePolicy(frame) {
+  const doc = frame.ownerDocument;
+  if (framePolicyWarned || !doc || hasNappletFramePolicy(doc)) return;
+  framePolicyWarned = true;
+  console.warn(
+    `[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>.`
+  );
+}
 function createNip5dTransport({ hooks, runtime, state: shellReadyState }) {
   const bindings = /* @__PURE__ */ new Map();
   function currentBinding(windowId) {
@@ -1404,6 +1422,7 @@ function createNip5dTransport({ hooks, runtime, state: shellReadyState }) {
     bindPort(windowId, sourceWindow, event.origin, ports[0]);
   }
   function observeFrame(frame, windowId) {
+    warnWithoutFramePolicy(frame);
     let loads = 0;
     const onLoad = () => {
       loads += 1;
@@ -1695,6 +1714,28 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
   const target = window;
   const allowed = new Set(domains);
   const requestTimeoutMs = 3e4;
+  const rtcGlobals = /* @__PURE__ */ new Set([
+    "webkitRTCPeerConnection",
+    "mozRTCPeerConnection",
+    "webkitRTCSessionDescription",
+    "mozRTCSessionDescription",
+    "webkitRTCIceCandidate",
+    "mozRTCIceCandidate"
+  ]);
+  for (const key of Object.getOwnPropertyNames(target)) {
+    if (key.startsWith("RTC")) rtcGlobals.add(key);
+  }
+  for (const rtcName of rtcGlobals) {
+    try {
+      Object.defineProperty(target, rtcName, {
+        value: void 0,
+        writable: false,
+        configurable: false,
+        enumerable: false
+      });
+    } catch {
+    }
+  }
   function id() {
     if (target.crypto?.randomUUID) return target.crypto.randomUUID();
     return `napplet-${Date.now()}-${Math.random().toString(16).slice(2)}`;
@@ -3483,6 +3524,7 @@ function createNotifyProxy(deps) {
 }
 export {
   ALL_CAPABILITIES2 as ALL_CAPABILITIES,
+  NAPPLET_FRAME_POLICY,
   NAPPLET_HELLO,
   TOPICS,
   adaptHooks,
@@ -3500,6 +3542,7 @@ export {
   denyNappletControllerAccess,
   formatDenialReason,
   getShellDomainState,
+  hasNappletFramePolicy,
   injectNappletCsp,
   injectNappletNamespacePrelude,
   manifestCache,
@@ -3508,6 +3551,7 @@ export {
   originRegistry,
   prepareNappletSrcdoc,
   renderNappletCspMeta,
+  renderNappletFramePolicyMeta,
   renderNappletNamespacePrelude,
   resolveShellEnvironment,
   sessionRegistry