@kehto/shell 0.22.0 → 0.24.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.
-- `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.
@@ -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
 
@@ -199,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
@@ -256,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
@@ -275,5 +274,16 @@ 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.
+
+## 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[];
 }
@@ -639,6 +647,38 @@ 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. */
@@ -1528,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 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 };
+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 };