@kehto/shell 0.21.3 → 0.23.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.
@@ -76,24 +76,23 @@ the prior opener-only interpretation is obsolete.
 
 ### NAP-INTENT binding and delivery
 
-Kehto implements merged [NAP-INTENT at
-`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`](https://github.com/napplet/naps/blob/5ac0490461ca6fec2f0d2e45b4835cf9bc08de24/naps/NAP-INTENT.md).
-The protected `window.napplet.intent` binding accepts structured
-`invoke(request)` calls and `open(archetype, payload?, opts?)`. It defaults
-`action` to `open`, preserves an optional queryless convention, rejects
-unsupported fields and caller-supplied sender data, and resolves only
-parent-originated correlated results.
-
-Successful results include `handled`, `handler`, `windowId`, and `convention`
-after target dispatch completes. Target delivery now follows NAP-INTENT at
-`25b29ee49e5bff8ebfe031f4b76dce98705c8b7e`: one `intent.deliver` envelope
-feeds the buffered `onDelivery` binding described below. Broader invocation and
-result changes from that newer spec remain deferred.
-
-Phase 105 completed released `@napplet/*` package adoption and persistent live
-Paja/playground catalogs and target controllers. The Phase 104 Paja simulator
-and playground catalog builder are historical exact-contract consumers; preserve
-archived planning rather than presenting it as active guidance.
+Kehto follows [NAP-INTENT PR #106](https://github.com/napplet/naps/blob/fc121fc264615482143eda86125863d2e1f741a2/naps/NAP-INTENT.md) at `fc121fc264615482143eda86125863d2e1f741a2`. The protected binding supports
+`window.napplet.intent.invoke('napplet:profile/open?pubkey=abc%2B123')` and
+`invoke(uri, { payload, handler, handlerHint, behavior })`. Query fields decode
+once into text; `+` remains literal. An explicit payload cannot accompany an
+inner query, and a `#naddr` recommendation cannot accompany `handlerHint`.
+Unsupported options and caller-supplied sender data are rejected. Only a
+parent-originated correlated result can settle the call.
+
+Successful results identify retained delivery responsibility with `ok`,
+`archetype`, `action`, `convention`, and an opaque `handler`. A target receives
+one parent-attested `intent.deliver`, buffered by `onDelivery` until registration.
+Acceptance is separate from later target completion.
+
+Legacy object-form `invoke(request)` and `open(archetype, payload?, opts?)`
+remain bounded compatibility adapters and warn once per iframe with
+`KEHTO_COMPAT_INTENT_OBJECT_INVOKE`. Their removal conditions are tracked in
+[compatibility](https://github.com/kehto/web/blob/main/docs/compatibility.md).
 
 ## Quick Start
 
@@ -136,11 +135,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
@@ -215,8 +255,8 @@ MIT
 
 ## NIP-5D event compatibility
 
-Current manifests use a direct artifact `x` hash, plain-text `content`, independent
-`z`/`i` routing declarations, and required `R` / optional `O` domains. Kehto also
+Current manifests use a direct artifact `x` hash, plain-text `content`, role-matched
+`z`/`i` intent declarations, and required `R` / optional `O` domains. Kehto also
 accepts legacy aggregate events through an isolated compatibility adapter.
 Existing `aggregateHash` host/cache/ACL fields carry the verified artifact hash
 for current events; legacy identities keep their original aggregate. Both paths
@@ -234,5 +274,12 @@ A throwing listener does not prevent delivery to other listeners.
 When no canonical listener is registered, matching legacy INC listeners can
 consume the delivery locally. This emits `KEHTO_COMPAT_INTENT_INC` once per
 iframe; a delivery is never replayed to both APIs. See [compatibility tracking](https://github.com/kehto/web/blob/main/docs/compatibility.md).
-This aligns delivery with NAP-INTENT at `25b29ee`; broader invocation/result
-changes and the packaged SDK upgrade remain deferred.
+Delivery and URI invocation follow NAP-INTENT PR #106 at
+`fc121fc264615482143eda86125863d2e1f741a2`; the packaged SDK still trails that
+contract, as documented in the conformance policy.
+
+## Paja URL integration
+
+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.

package/dist/index.d.ts

@@ -639,6 +639,114 @@ declare function renderNappletNamespacePrelude(options: NappletNamespacePreludeO
  */
 declare function injectNappletNamespacePrelude(html: string, options: NappletNamespacePreludeOptions): string;
 
+/** Canonical request fields produced from a NAP-INTENT convention URI. */
+interface NormalizedIntentUri {
+    archetype: string;
+    action: string;
+    convention: string;
+    payload?: unknown;
+    handlerHint?: {
+        address: string;
+        relays?: string[];
+    };
+    handler?: string;
+    behavior?: {
+        focus?: boolean;
+        reuse?: boolean;
+    };
+}
+/**
+ * Normalize a NAP-INTENT convention URI.
+ *
+ * The host and injected NIP-5D binding use the same normalizer factory.
+ *
+ * @param uri - Complete NAP-INTENT convention URI.
+ * @param options - Optional payload, handler, recommendation, and behavior hints.
+ * @returns The canonical request fields for `intent.invoke`.
+ * @example
+ * ```ts
+ * normalizeIntentUri('napplet:profile/open?pubkey=abc%2B123');
+ * // { archetype: 'profile', action: 'open', convention: 'napplet:profile/open', payload: { pubkey: 'abc+123' } }
+ * ```
+ */
+declare const normalizeIntentUri: (uri: unknown, options?: unknown) => NormalizedIntentUri;
+
+/** 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 +1560,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 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 };