@kehto/shell 0.23.0 → 0.24.1

package/README.md

@@ -34,7 +34,7 @@ Current draft behaviors this package enforces:
   when the runtime can identify it. The shell forwards this optional context
   without imposing a consent policy; host runtimes may ignore it or use it to
   resolve their own identity-scoped signer decisions.
-- `prepareNappletSrcdoc()` inserts validated CSP first, then the NIP-5D bootstrap and mandatory NAP-SHELL shim, outside verified artifact bytes. The shim installs the parent-bound `shell.init` receiver, emits one `shell.ready`, and exposes callable NAP interfaces before authored scripts run. Optional namespaces are filtered to the bare-domain allowlist; `shell` is always retained. Published core 0.32.0 and shim 0.30.0 omit generic mandatory shell, so Kehto retains this host-owned prelude under NAP-SHELL `5ac0490461ca6fec2f0d2e45b4835cf9bc08de24` until an upstream correction is reviewed.
+- `prepareNappletSrcdoc()` inserts validated CSP and the runtime namespace outside verified artifact bytes. It exposes only the host-selected bare domains. Optional `shell` installs its parent-bound receiver before readiness; routing uses trusted iframe creation identity independently of that exchange. See the living [NAP-SHELL](https://github.com/napplet/naps/blob/master/naps/NAP-SHELL.md).
 - The injected resource projection follows draft NAP-RESOURCE `9511232f69313aa7953d110e35d32cc28d506f66`: `bytes(url, { servers? })` carries advisory Blossom locations and `bytesMany(requests)` keeps each `{ url, servers? }` entry intact.
 - `window.napplet.shell.supports(domain)` answers synchronously and locally from the cached first `shell.init` environment. It returns `false` before `shell.init`, for unknown values, and for domains that are not live and granted to that napplet; it never sends a support-query message.
 - Five optional per-domain proxies — `createIdentityProxy`, `createThemeProxy`, `createKeysProxy`, `createMediaProxy`, `createNotifyProxy` — can be composed between napplet and runtime to intercept request traffic per NAP. They are NOT wired by default. Identity/theme proxy `emit()` compatibility members fail closed; hosts must deliver automatic changes through `ShellBridge.publishIdentityChanged()` / `publishTheme()`, which enforce live session, granted domain, and current ACL.
@@ -198,7 +198,7 @@ automatic changes are accepted only when their `MessageEvent.source` is
 the canonical operations.
 
 `ShellBridge` delivers `identity.changed` and `theme.changed` exactly once per
-eligible recipient: a live authenticated `shell.ready` session, its frozen
+eligible recipient: a live authenticated source-bound session, its frozen
 environment includes the relevant domain, and its current recipient read
 capability is still granted. Identity sign-out is `pubkey: ""`. Theme updates
 arrive only after the service has stored the complete color state. These are
@@ -283,3 +283,7 @@ contract, as documented in the conformance policy.
 The shell normalizer also powers Paja intent links. See the
 [Paja guide](https://kehto.github.io/web/docs/packages/paja.html#nap-intent-links-and-lifecycle)
 for outer URL encoding, review, routing, and verified launcher behavior.
+
+## GAMEPAD integration
+
+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 and the playground register 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).

package/dist/index.d.ts

@@ -327,7 +327,7 @@ interface UnroutedMessageInfo {
 /**
  * Static capability set sent to napplet iframes through the shell.ready /
  * shell.init handshake. Optional runtime domain presence is injected before
- * authored code, while mandatory NAP-SHELL caches this environment for local
+ * authored code, while optional NAP-SHELL caches this environment for local
  * capability queries.
  *
  * NAP-SHELL needs only a truthful set of bare domain names. The shim answers
@@ -584,6 +584,14 @@ interface ShellBridge {
 }
 declare function createShellBridge(hooks: ShellAdapter): ShellBridge;
 
+/**
+ * Restrict native controller/device APIs before assigning a napplet document.
+ * @param frame Host-owned iframe, before its authored code executes.
+ * @returns Nothing; unrelated Permissions-Policy entries are retained.
+ * @example denyNappletControllerAccess(frame);
+ */
+declare function denyNappletControllerAccess(frame: Pick<HTMLIFrameElement, 'getAttribute' | 'setAttribute'>): void;
+
 /**
  * The injected implementation must remain one self-contained function: the
  * renderer serializes it ahead of verified artifact scripts without changing
@@ -605,7 +613,7 @@ declare function createShellBridge(hooks: ShellAdapter): ShellBridge;
 interface NappletNamespacePreludeOptions {
     /**
      * Optional bare NAP domain names the shell exposes to this napplet.
-     * Mandatory `shell` is injected even when omitted here.
+     * Shell is injected only when included in the exposed domains.
      */
     domains: readonly string[];
 }
@@ -1560,4 +1568,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 ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappletCspDirective, type NappletCspDirectives, type NappletCspOptions, type NappletNamespacePreludeOptions, 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 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, 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 ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappletCspDirective, type NappletCspDirectives, type NappletCspOptions, type NappletNamespacePreludeOptions, 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 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, injectNappletCsp, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, normalizeIntentUri, originRegistry, prepareNappletSrcdoc, renderNappletCspMeta, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };

package/dist/index.js

@@ -976,6 +976,7 @@ var audioManager = {
 
 // src/shell-init.ts
 var RUNTIME_NATIVE_DOMAINS = [
+  "shell",
   "relay",
   "identity",
   "storage",
@@ -1000,7 +1001,8 @@ var SERVICE_ONLY_DOMAINS = [
   "webrtc",
   "dm",
   "count",
-  "fs"
+  "fs",
+  "gamepad"
 ];
 function buildShellCapabilities(hooks) {
   const disabled = new Set(hooks.capabilities?.disabledDomains ?? []);
@@ -1096,14 +1098,21 @@ function handleShellReady({
   if (state.initSent.get(sourceWindow) === sourceRegistrationId) {
     return;
   }
-  const identity = resolveNip5dIdentity(hooks, windowId, sourceWindow);
-  if (!identity) return;
-  registerNip5dSessionIfNeeded({ origin, runtime, state, sourceRegistrationId, windowId, identity });
-  const environment = originRegistry.getEnvironment(sourceWindow) ?? resolveShellEnvironment(hooks, identity);
-  state.environments.set(windowId, environment);
+  const environment = registerSourceSession({ hooks, origin, runtime, state, sourceRegistrationId, sourceWindow, windowId });
+  if (!environment?.capabilities.domains.includes("shell")) return;
   postShellInit(sourceWindow, environment);
   state.initSent.set(sourceWindow, sourceRegistrationId);
 }
+function registerSourceSession(options) {
+  const { hooks, origin, runtime, state, sourceRegistrationId, sourceWindow, windowId } = options;
+  const identity = resolveNip5dIdentity(hooks, windowId, sourceWindow, runtime.sessionRegistry.getEntryByWindowId(windowId));
+  if (!identity) return null;
+  registerNip5dSessionIfNeeded({ origin, runtime, state, sourceRegistrationId, windowId, identity });
+  const existing = state.environments.get(windowId);
+  const environment = originRegistry.getEnvironment(sourceWindow) ?? existing ?? resolveShellEnvironment(hooks, identity);
+  state.environments.set(windowId, environment);
+  return environment;
+}
 function registerNip5dSessionIfNeeded({
   origin,
   runtime,
@@ -1118,9 +1127,14 @@ function registerNip5dSessionIfNeeded({
     return;
   }
   if (existing && previousRegistration !== void 0) {
+    runtime.destroyWindow(windowId);
     runtime.sessionRegistry.unregister(windowId);
+    state.environments.delete(windowId);
+  }
+  if (existing && previousRegistration === void 0) {
+    state.sessionRegistration.set(windowId, sourceRegistrationId);
+    return;
   }
-  if (existing && previousRegistration === void 0) return;
   const entry = {
     pubkey: "",
     windowId,
@@ -1135,7 +1149,7 @@ function registerNip5dSessionIfNeeded({
   runtime.sessionRegistry.register(windowId, entry);
   state.sessionRegistration.set(windowId, sourceRegistrationId);
 }
-function resolveNip5dIdentity(hooks, windowId, sourceWindow) {
+function resolveNip5dIdentity(hooks, windowId, sourceWindow, existingSession) {
   const hookIdentity = hooks.onNip5dIframeCreate?.(windowId);
   if (hookIdentity !== null && hookIdentity !== void 0) {
     return Object.freeze({
@@ -1145,7 +1159,8 @@ function resolveNip5dIdentity(hooks, windowId, sourceWindow) {
   }
   const originIdentity = originRegistry.getIdentity(sourceWindow);
   if (!originIdentity) {
-    return null;
+    if (existingSession?.provenance !== "nip-5d" || typeof existingSession.dTag !== "string" || typeof existingSession.aggregateHash !== "string") return null;
+    return Object.freeze({ dTag: existingSession.dTag, aggregateHash: existingSession.aggregateHash });
   }
   return Object.freeze({
     dTag: originIdentity.dTag,
@@ -1208,6 +1223,15 @@ function createShellBridge(hooks) {
       }
       const msg = event.data;
       if (typeof msg !== "object" || msg === null || typeof msg.type !== "string") return;
+      if (!registerSourceSession({
+        hooks,
+        origin: event.origin,
+        runtime,
+        state: shellReadyState,
+        sourceRegistrationId: originRegistry.getRegistrationId(sourceWindow) ?? 0,
+        sourceWindow,
+        windowId
+      })) return;
       if (msg.type === "shell.ready") {
         handleShellReady({
           hooks,
@@ -1246,6 +1270,13 @@ function createShellBridge(hooks) {
   };
 }
 
+// src/gamepad-policy.ts
+var CONTROLLER_FEATURES = ["gamepad", "hid", "usb"];
+function denyNappletControllerAccess(frame) {
+  const remaining = (frame.getAttribute("allow") ?? "").split(";").map((entry) => entry.trim()).filter((entry) => entry && !CONTROLLER_FEATURES.some((feature) => entry === feature || entry.startsWith(`${feature} `)));
+  frame.setAttribute("allow", [...remaining, ...CONTROLLER_FEATURES.map((feature) => `${feature} 'none'`)].join("; "));
+}
+
 // src/intent-uri.ts
 function createIntentUriNormalizer() {
   const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
@@ -1439,7 +1470,7 @@ function scriptJson(value) {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
 function renderNappletNamespacePrelude(options) {
-  const domains = uniqueBareDomains(["shell", ...options.domains]);
+  const domains = uniqueBareDomains(options.domains);
   return `<script data-kehto-nip5d-injection>(${nappletNamespacePrelude.toString()})(${scriptJson(domains)}, (${createIntentUriNormalizer.toString()})());</script>`;
 }
 function injectNappletNamespacePrelude(html, options) {
@@ -1628,7 +1659,7 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
       return Object.freeze(strings);
     }
     function supports(domain) {
-      return typeof domain === "string" && environment?.capabilities.domains.includes(domain) === true;
+      return typeof domain === "string" && !!target.napplet && Object.prototype.hasOwnProperty.call(target.napplet, domain);
     }
     const shell2 = {
       ready: () => ready,
@@ -2709,6 +2740,63 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
       })
     };
   }
+  function makeGamepad() {
+    let state = { available: true, focused: false, pads: [] };
+    const handlers = /* @__PURE__ */ new Set();
+    const copy = (value) => ({
+      available: value.available,
+      focused: value.focused,
+      ...value.reason === void 0 ? {} : { reason: value.reason },
+      pads: value.pads.map((pad) => pad === null ? null : {
+        index: pad.index,
+        id: pad.id,
+        mapping: pad.mapping,
+        connected: true,
+        timestamp: pad.timestamp,
+        axes: [...pad.axes],
+        buttons: pad.buttons.map(({ value: value2, pressed, touched }) => ({ value: value2, pressed, touched }))
+      })
+    });
+    const numberIn = (value, min, max) => typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+    const valid = (value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+      const candidate = value;
+      if (typeof candidate.available !== "boolean" || typeof candidate.focused !== "boolean" || !Array.isArray(candidate.pads)) return false;
+      if (candidate.available ? candidate.reason !== void 0 : candidate.focused || !["blocked", "unavailable"].includes(candidate.reason ?? "")) return false;
+      return Array.from(candidate.pads).every((pad) => {
+        if (pad === null) return true;
+        if (!pad || typeof pad !== "object" || !Number.isInteger(pad.index) || pad.index < 0 || typeof pad.id !== "string" || typeof pad.mapping !== "string" || pad.connected !== true || !Number.isFinite(pad.timestamp) || !Array.isArray(pad.axes) || !Array.isArray(pad.buttons)) return false;
+        if (!candidate.focused && pad.timestamp !== 0) return false;
+        if (!Array.from(pad.axes).every((axis) => numberIn(axis, -1, 1) && (candidate.focused || axis === 0))) return false;
+        return Array.from(pad.buttons).every((button) => button && numberIn(button.value, 0, 1) && typeof button.pressed === "boolean" && typeof button.touched === "boolean" && (candidate.focused || button.value === 0 && !button.pressed && !button.touched));
+      });
+    };
+    listen((event) => {
+      if (!isParentMessage(event)) return;
+      const incoming = event.data;
+      if (!incoming || incoming.type !== "gamepad.state" || "id" in incoming || !valid(incoming)) return;
+      state = copy(incoming);
+      const snapshot = copy(state);
+      const recipients = Array.from(handlers);
+      for (const entry of recipients) if (handlers.has(entry)) entry.handler(copy(snapshot));
+    });
+    const api = {
+      get available() {
+        return state.available;
+      },
+      get focused() {
+        return state.focused;
+      },
+      getGamepads: () => copy(state).pads,
+      onChange(handler) {
+        const entry = { handler };
+        handlers.add(entry);
+        return subscriptionHandle(() => handlers.delete(entry));
+      }
+    };
+    post({ type: "gamepad.subscribe" });
+    return api;
+  }
   function makeDm() {
     const req = (type, payload) => request({ type, ...payload }, `${type}.result`, withoutEnvelope, { rejectOnError: false });
     return {
@@ -2755,7 +2843,8 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
     };
   }
   const intentDelivery = allowed.has("intent") ? makeIntentDelivery() : void 0;
-  const shell = makeShell();
+  const shell = allowed.has("shell") ? makeShell() : void 0;
+  let gamepad;
   let inc;
   let identity;
   let theme;
@@ -2778,9 +2867,10 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
     return intent;
   }
   function isProtectedDomain(domain) {
-    return domain === "shell" || domain === "inc" || domain === "identity" || domain === "theme" || domain === "intent";
+    return domain === "gamepad" || domain === "shell" || domain === "inc" || domain === "identity" || domain === "theme" || domain === "intent";
   }
   function makeDomain(domain, existing) {
+    if (domain === "gamepad") return gamepad ??= makeGamepad();
     if (domain === "shell") return shell;
     if (domain === "inc") return makeProtectedInc(existing);
     if (domain === "identity") return makeProtectedIdentity();
@@ -3094,6 +3184,7 @@ export {
   createNotifyProxy,
   createShellBridge,
   createThemeProxy,
+  denyNappletControllerAccess,
   formatDenialReason,
   injectNappletCsp,
   injectNappletNamespacePrelude,