@kehto/shell 0.21.3 → 0.22.0

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.
-- `injectNappletNamespacePrelude()` implements the NIP-5D injected-domain bootstrap and mandatory NAP-SHELL shim: hosts prepend it to `srcdoc` outside verified artifact bytes, install the parent-bound `shell.init` receiver, emit one `shell.ready`, and expose 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 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.
 - 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.
@@ -136,11 +136,52 @@ const bridge = createShellBridge({
 ```
 
 ### Shell init
+- `prepareNappletSrcdoc` — recommended verified-document entry point; applies CSP and namespace together
+- `buildNappletCsp`, `renderNappletCspMeta`, `injectNappletCsp` — shared policy construction and CSP-only composition utilities
 - `buildShellCapabilities` — construct the immutable domain-only `ShellCapabilities` payload emitted during the `shell.ready` / `shell.init` handshake
 - `resolveShellEnvironment(hooks, identity)` — host-integrator-only utility that narrows the live environment for a trusted creation-time identity before `shell.init`; it is not installed on `window.napplet` and is not a shim-facing napplet API
-- `injectNappletNamespacePrelude` — insert a host-owned NIP-5D `window.napplet` callable-domain prelude into verified HTML before authored scripts
+- `injectNappletNamespacePrelude` — low-level bootstrap-only insertion for development wrappers; does not apply CSP
 - `renderNappletNamespacePrelude` — render only the bootstrap `<script>` for hosts that already own HTML insertion
 
+### Host CSP overrides
+
+Resolve and verify the signed manifest, aggregate and artifact bytes before
+calling `prepareNappletSrcdoc`. Keep the verified bytes for identity and caching;
+only the rendered copy receives policy and bootstrap. Bind the iframe window to
+the verified identity before assigning `srcdoc`, with `sandbox="allow-scripts"`.
+
+```ts
+import { prepareNappletSrcdoc } from '@kehto/shell';
+
+const srcdoc = prepareNappletSrcdoc(verifiedHtml, {
+  domains: ['theme'],
+  csp: {
+    connectOrigins: ['https://api.example'],
+    directives: { 'media-src': ['blob:'], 'img-src': ['data:'] },
+  },
+});
+```
+
+Omitting `csp` applies NIP-5D's conservative baseline, including WASM compilation.
+Directive overrides replace individual source lists. They cannot disable CSP
+insertion, allow `'unsafe-eval'`, or suppress the inline namespace bootstrap.
+`connect-src` defaults to the exact `connectOrigins` grants and can be narrowed;
+wildcards, scheme-wide grants, credentials, paths, query strings and fragments
+are rejected. Empty source lists are rejected; use `["'none'"]` to deny a
+directive. Hosts may remove WASM permission by setting
+`'script-src': ["'unsafe-inline'"]`.
+
+`script-src` and an explicit `script-src-elem` must permit the inline bootstrap.
+Nonce/hash/`strict-dynamic` combinations that suppress that allowance are rejected;
+nonce-based bootstrap authorization is not supported by this API. Existing
+artifact CSP and inherited response policies still apply cumulatively and may
+block execution; this helper never strips them to make a napplet run.
+
+Meta-unsupported directives (`frame-ancestors`, `sandbox`, `report-uri`) and
+unsupported directive names are rejected. Configure embedding restrictions on
+the host HTTP response. See the [CSP enforcement contract](https://github.com/kehto/web/blob/main/docs/policies/NIP-5D-CONFORMANCE.md#shell-csp-enforcement)
+for normative requirements, enforced recommendations and configurable defaults.
+
 ### Domain proxies (NIP-5D composition seams)
 - `createIdentityProxy` — intercept identity read requests; direct `emit()` is prohibited
 - `createThemeProxy` — intercept `theme.get`; direct `emit()` is prohibited

package/dist/index.d.ts

@@ -639,6 +639,82 @@ declare function renderNappletNamespacePrelude(options: NappletNamespacePreludeO
  */
 declare function injectNappletNamespacePrelude(html: string, options: NappletNamespacePreludeOptions): string;
 
+/** Source-list directives supported by the shell's meta-delivered CSP. */
+type NappletCspDirective = 'default-src' | 'script-src' | 'script-src-elem' | 'script-src-attr' | 'style-src' | 'style-src-elem' | 'style-src-attr' | 'img-src' | 'font-src' | 'connect-src' | 'worker-src' | 'child-src' | 'frame-src' | 'media-src' | 'object-src' | 'manifest-src' | 'base-uri' | 'form-action';
+/** Host replacements for individual CSP source lists; omitted directives retain defaults. */
+type NappletCspDirectives = Readonly<Partial<Record<NappletCspDirective, readonly string[]>>>;
+/** Host policy for a verified napplet's CSP, separate from its signed manifest. */
+interface NappletCspOptions {
+    /** Explicit HTTP(S)/WS(S) origins granted direct connections; defaults to none. */
+    readonly connectOrigins?: readonly string[];
+    /** Source-list replacements. connect-src may only narrow the explicit grants. */
+    readonly directives?: NappletCspDirectives;
+}
+/**
+ * Build the default NIP-5D CSP with validated host source-list replacements.
+ * Meta-unsupported directives must be configured on the host HTTP response.
+ *
+ * @param options - Explicit connection grants and directive replacements.
+ * @returns A serialized policy. Invalid or conflicting overrides throw.
+ * @example
+ * ```ts
+ * const policy = buildNappletCsp({
+ *   connectOrigins: ['https://api.example'],
+ *   directives: { 'media-src': ['blob:'] },
+ * });
+ * ```
+ */
+declare function buildNappletCsp(options?: NappletCspOptions): string;
+/**
+ * Render the shell's validated CSP meta element.
+ *
+ * @param options - Explicit connection grants and directive replacements.
+ * @returns An attribute-escaped CSP meta element for the first position in head.
+ * @example
+ * ```ts
+ * const meta = renderNappletCspMeta({ directives: { 'img-src': ['data:'] } });
+ * ```
+ */
+declare function renderNappletCspMeta(options?: NappletCspOptions): string;
+/**
+ * Insert CSP before authored content. The caller must verify the artifact first.
+ * Existing authored CSP remains in place and can only further restrict execution.
+ *
+ * @param html - Already-verified artifact HTML; never use the result for its hash.
+ * @param options - Explicit connection grants and directive replacements.
+ * @returns A srcdoc copy with the CSP first in head.
+ * @example
+ * ```ts
+ * const protectedHtml = injectNappletCsp(verifiedHtml);
+ * ```
+ */
+declare function injectNappletCsp(html: string, options?: NappletCspOptions): string;
+
+/** Shell bootstrap availability and host CSP for a verified napplet document. */
+interface NappletSrcdocOptions extends NappletNamespacePreludeOptions {
+    /** Validated host policy changes. Omission uses the NIP-5D baseline. */
+    readonly csp?: NappletCspOptions;
+}
+/**
+ * Prepare verified artifact HTML with CSP first, then the mandatory namespace.
+ * There is no CSP opt-out. Resolve and verify the artifact before calling this;
+ * bind its identity to the sandboxed iframe before assigning the returned srcdoc.
+ * Keep the original verified bytes for hashing and caching.
+ *
+ * @param html - Already-verified napplet artifact HTML.
+ * @param options - Exposed domains and validated host CSP changes.
+ * @returns Srcdoc HTML with policy and bootstrap preceding authored content.
+ * @example
+ * ```ts
+ * iframe.sandbox.value = 'allow-scripts';
+ * iframe.srcdoc = prepareNappletSrcdoc(verifiedHtml, {
+ *   domains: ['shell', 'theme'],
+ *   csp: { directives: { 'media-src': ['blob:'] } },
+ * });
+ * ```
+ */
+declare function prepareNappletSrcdoc(html: string, options: NappletSrcdocOptions): string;
+
 /**
  * Manifest cache — persists verified NIP-5A aggregate hashes per napplet identity.
  */
@@ -1452,4 +1528,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 NappletNamespacePreludeOptions, 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, buildShellCapabilities, createIdentityProxy, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, originRegistry, 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 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, originRegistry, prepareNappletSrcdoc, renderNappletCspMeta, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };

package/dist/index.js

@@ -2694,6 +2694,124 @@ function nappletNamespacePrelude(domains) {
   });
 }
 
+// src/napplet-head.ts
+function insertNappletHead(html, content) {
+  const opening = /^([\t\n\f\r ]*(?:<!doctype[\t\n\f\r ]+html[\t\n\f\r ]*>[\t\n\f\r ]*)?(?:<html>[\t\n\f\r ]*)?)(<head>)?/i.exec(html);
+  const prefix = opening[0];
+  const insertion = opening[2] ? content : `<head>${content}</head>`;
+  return `${prefix}${insertion}${html.slice(prefix.length)}`;
+}
+
+// src/napplet-csp.ts
+var DEFAULT_DIRECTIVES = {
+  "default-src": ["'none'"],
+  "script-src": ["'unsafe-inline'", "'wasm-unsafe-eval'"],
+  "style-src": ["'unsafe-inline'"],
+  "img-src": ["data:", "blob:"],
+  "font-src": ["data:"],
+  "connect-src": ["'none'"],
+  "worker-src": ["'none'"],
+  "child-src": ["'none'"],
+  "frame-src": ["'none'"],
+  "media-src": ["'none'"],
+  "object-src": ["'none'"],
+  "manifest-src": ["'none'"],
+  "base-uri": ["'none'"],
+  "form-action": ["'none'"]
+};
+var OPTIONAL_DIRECTIVES = /* @__PURE__ */ new Set([
+  "script-src-elem",
+  "script-src-attr",
+  "style-src-elem",
+  "style-src-attr"
+]);
+var KEYWORDS = /* @__PURE__ */ new Set([
+  "'none'",
+  "'self'",
+  "'unsafe-inline'",
+  "'wasm-unsafe-eval'",
+  "'unsafe-hashes'",
+  "'strict-dynamic'",
+  "'report-sample'"
+]);
+function connectionOrigin(source) {
+  let url;
+  try {
+    url = new URL(source);
+  } catch {
+    throw new Error(`CSP connection grant must be an exact HTTP(S)/WS(S) origin: ${source}`);
+  }
+  if (!/^(https?|wss?):$/.test(url.protocol) || url.username || url.password || url.pathname !== "/" && url.pathname !== "" || url.search || url.hash || /[\s*\\;,"<>'`]/.test(source + url.origin) || !source.startsWith(`${url.protocol}//`)) {
+    throw new Error(`CSP connection grant must be an exact HTTP(S)/WS(S) origin: ${source}`);
+  }
+  return url.origin;
+}
+function validateSources(directive, sources2) {
+  if (!Array.isArray(sources2) || sources2.length === 0) {
+    throw new Error(`CSP ${directive} needs a nonempty source list; use 'none' to deny it`);
+  }
+  const result = [...new Set(sources2)];
+  for (const source of result) {
+    if (typeof source !== "string" || !/^[\x21-\x7e]+$/.test(source) || /[;,"<>\\]/.test(source)) {
+      throw new Error(`Invalid CSP source in ${directive}`);
+    }
+    if (source.toLowerCase() === "'unsafe-eval'") {
+      throw new Error("NIP-5D CSP forbids 'unsafe-eval'; use 'wasm-unsafe-eval' for WebAssembly");
+    }
+    if (source.includes("'") && !KEYWORDS.has(source) && !/^'(?:nonce-|sha(?:256|384|512)-)[A-Za-z0-9+/_-]+=*'$/.test(source)) {
+      throw new Error(`Invalid CSP keyword in ${directive}: ${source}`);
+    }
+  }
+  if (result.includes("'none'") && result.length !== 1) {
+    throw new Error(`CSP ${directive} cannot combine 'none' with other sources`);
+  }
+  return result;
+}
+function requireBootstrapScripts(directive, sources2) {
+  if (!sources2.includes("'unsafe-inline'") || sources2.some(
+    (source) => /^'(?:nonce-|sha(?:256|384|512)-|strict-dynamic')/.test(source)
+  )) {
+    throw new Error(`CSP ${directive} must allow the shell's inline namespace bootstrap`);
+  }
+}
+function buildNappletCsp(options = {}) {
+  const grants = [...new Set((options.connectOrigins ?? []).map(connectionOrigin))].sort();
+  const policy = {
+    ...DEFAULT_DIRECTIVES,
+    "connect-src": grants.length ? grants : ["'none'"]
+  };
+  for (const [directive, sources2] of Object.entries(options.directives ?? {})) {
+    if (!Object.hasOwn(DEFAULT_DIRECTIVES, directive) && !OPTIONAL_DIRECTIVES.has(directive)) {
+      throw new Error(`Unsupported meta CSP directive: ${directive}`);
+    }
+    policy[directive] = validateSources(directive, sources2);
+  }
+  const connect = policy["connect-src"];
+  if (!(connect.length === 1 && connect[0] === "'none'")) {
+    policy["connect-src"] = [...new Set(connect.map((source) => {
+      const origin = connectionOrigin(source);
+      if (!grants.includes(origin)) throw new Error(`CSP connection origin was not granted: ${origin}`);
+      return origin;
+    }))].sort();
+  }
+  requireBootstrapScripts("script-src", policy["script-src"]);
+  if (policy["script-src-elem"]) requireBootstrapScripts("script-src-elem", policy["script-src-elem"]);
+  return Object.entries(policy).map(([name, sources2]) => `${name} ${sources2.join(" ")}`).join("; ");
+}
+function renderNappletCspMeta(options = {}) {
+  const policy = buildNappletCsp(options).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+  return `<meta http-equiv="Content-Security-Policy" content="${policy}">`;
+}
+function injectNappletCsp(html, options = {}) {
+  return insertNappletHead(html, renderNappletCspMeta(options));
+}
+
+// src/napplet-srcdoc.ts
+function prepareNappletSrcdoc(html, options) {
+  const meta = renderNappletCspMeta(options.csp);
+  return insertNappletHead(html, meta + renderNappletNamespacePrelude(options));
+}
+
 // src/index.ts
 import { ALL_CAPABILITIES as ALL_CAPABILITIES2 } from "@kehto/runtime";
 import { createEnforceGate, createNapEnforceGate, formatDenialReason } from "@kehto/runtime";
@@ -2772,6 +2890,7 @@ export {
   TOPICS,
   adaptHooks,
   audioManager,
+  buildNappletCsp,
   buildShellCapabilities,
   createEnforceGate,
   createIdentityProxy,
@@ -2782,10 +2901,13 @@ export {
   createShellBridge,
   createThemeProxy,
   formatDenialReason,
+  injectNappletCsp,
   injectNappletNamespacePrelude,
   manifestCache,
   nappKeyRegistry,
   originRegistry,
+  prepareNappletSrcdoc,
+  renderNappletCspMeta,
   renderNappletNamespacePrelude,
   resolveShellEnvironment,
   sessionRegistry