@kehto/shell

Browser adapter over @kehto/runtime for iframe/session hosting.

Alpha status: Kehto is an early runtime implementation for a draft NIP-5D protocol. Injected-domain behavior and NAP contracts are not final.

Install

pnpm add @kehto/shell @kehto/runtime @kehto/acl @napplet/core @napplet/nap nostr-tools

Manifest Facts

Field	Value
Source	packages/shell/package.json, packages/shell/src/index.ts
Version	0.20.0
Runtime entry	./dist/index.js
Types entry	./dist/index.d.ts
Dependencies	@kehto/acl, @kehto/runtime
Side effects	false

Peer Dependencies

Package	Range
@napplet/core	>=0.31.0 <0.32.0
@napplet/nap	>=0.31.0 <0.32.0
nostr-tools	>=2.23.3 <=2.x

Primary APIs

Area	Exports
Factory	createShellBridge, ShellBridge
Hooks	adaptHooks, BrowserDeps, ShellAdapter, ShellCapabilities, UploadHooks, IntentHooks, LinkHooks, CommonHooks, ListsHooks, SerialHooks, BleHooks, WebrtcHooks, DmHooks, UnroutedMessageInfo
Protocol and capability types	NostrEvent, NostrFilter, NappletMessage, Capability, ALL_CAPABILITIES
Shell init and bootstrap	buildShellCapabilities, injectNappletNamespacePrelude, renderNappletNamespacePrelude, NappletNamespacePreludeOptions
Registries and caches	sessionRegistry, nappKeyRegistry, originRegistry, manifestCache, audioManager, PendingUpdate, ManifestCacheEntry, AudioSource
Enforcement re-exports	createEnforceGate, createNapEnforceGate, formatDenialReason, EnforceResult, EnforceConfig, NapEnforceConfig, IdentityResolver, AclChecker, NapMessage
Proxies	createIdentityProxy, createThemeProxy, createKeysProxy, createMediaProxy, createNotifyProxy
Shell-owned internal models	resource request/result/error types
Topics	TOPICS, TopicKey, TopicValue

Scope Boundaries

• Owns browser integration: window, postMessage, iframe session identity, gateway loading, shell capabilities, origin/session registries, and browser-specific adapters.
• Forwards an asynchronous RelayPoolLike.publish() promise through its runtime adapter so relay.publish.result reflects transport settlement.
• Preserves an asynchronous RelayPoolHooks.publishToScopedRelay() result so scoped publication does not report success before transport acceptance.
• Provides injectNappletNamespacePrelude() for optional NIP-5D domains plus mandatory NAP-SHELL before authored srcdoc scripts execute. The prelude installs its receiver before one shell.ready, caches the first parent shell.init, and prevents napplet namespace reassignment from removing shell.
• The published @napplet/core@0.31.1 and @napplet/shim@0.29.2 line does not supply a generic mandatory shell surface. Kehto therefore retains this host-owned prelude under NAP-SHELL 5ac0490461ca6fec2f0d2e45b4835cf9bc08de24 until an upstream correction is reviewed.
• Advertises count in shell capabilities and the injected window.napplet namespace only when ShellAdapter.services.count is wired, so shell.supports("count") tracks an actual NAP-COUNT backend.
• Surfaces unroutable inbound messages via the optional ShellAdapter.onUnroutedMessage hook (UnroutedMessageInfo) — observe-only; the bridge still drops messages from unidentified or unregistered windows, but hosts can now log them instead of debugging a silent vanish.
• Advertises and injects dm or fs only when the matching runtime service is registered and host domain policy permits it.
• Treats keys.forward as napplet-to-shell only; shell-initiated key actions are emitted as keys.action through the keys proxy/runtime service path.
• Keeps identity/theme proxy delivery fail-closed. Hosts publish automatic changes only through ShellBridge.publishIdentityChanged() / publishTheme(), which filter by live session, granted domain, and current ACL.
• Must not expose window.nostr to napplets.
• Does not implement service behavior itself; register reference services from @kehto/services on the underlying runtime.

API Reference

• Generated module: docs/api/modules/_kehto_shell.html