Documentation
    Preparing search index...

    Interface ShellBridge

    Shell-side message bridge that handles NIP-5D communication with napplet iframes.

    The bridge acts as a browser adapter: it receives raw MessageEvents from window.addEventListener('message', ...), extracts the source Window, resolves it to a windowId via originRegistry, and delegates NIP-5D envelope messages to the runtime engine. The shell.ready/shell.init capability handshake is handled locally within the bridge and never forwarded to the runtime.

    import { createShellBridge } from '@kehto/shell';

    const bridge = createShellBridge(hooks);
    window.addEventListener('message', bridge.handleMessage);
    interface ShellBridge {
        runtime: Runtime;
        destroy(): void;
        handleMessage(event: MessageEvent): void;
        injectEvent(topic: string, payload: unknown): void;
        publishIdentityChanged(pubkey: string): void;
        publishTheme(theme: Theme): void;
        registerConsentHandler(handler: (request: ConsentRequest) => void): void;
    }
    Index

    Properties

    runtime

    Methods

    destroy handleMessage injectEvent publishIdentityChanged publishTheme registerConsentHandler

    Properties

    runtime: Runtime

    Access the underlying runtime instance for advanced use cases. Provides direct access to the runtime's sessionRegistry, aclState, and manifestCache.

    Methods

    • Destroy the bridge instance, cleaning up all internal state. Persists manifest cache and clears all subscriptions, buffers, and registries. Call when the shell is shutting down or the bridge is no longer needed.

      Returns void

      bridge.destroy();

    • Handle an incoming postMessage from a napplet iframe.

      Only NIP-5D envelope objects (plain objects with a .type string) are accepted. NIP-01 arrays and all other message shapes are silently dropped (clean break — no legacy array fallback).

      shell.ready messages are handled locally: the bridge responds with shell.init containing the capability set and registered service list. All other envelopes are delegated to the runtime's NAP domain dispatch.

      Parameters

      • event: MessageEvent

        The raw MessageEvent from window.addEventListener('message', ...)

      Returns void

      window.addEventListener('message', bridge.handleMessage);

    • Inject a shell-originated event into subscription delivery. Under NIP-5D, shell-originated events are forwarded to napplets as inc.event envelope messages. The runtime's injectEvent() handles the per-session routing.

      v1.10 hard-removed the v1.8 soft-rename compatibility branch for the old auth:identity-changed topic. Use the canonical identity:changed topic for identity-change pushes.

      Parameters

      • topic: string

        The event topic tag value. Forwarded exactly once.

      • payload: unknown

        The event content

      Returns void

      bridge.injectEvent('identity:changed', { pubkey: userPubkey });

    • Publish the current shell-user identity to every loaded napplet.

      Posts an identity.changed envelope (shell → napplet push) with the current user pubkey. An empty pubkey means no signer/user identity is currently connected. This is distinct from NIP-5D napplet session identity, which remains source-bound at iframe creation.

      Parameters

      • pubkey: string

        Current user's hex pubkey, or empty string when signed out.

      Returns void

    • Publish a theme update to each eligible napplet.

      Posts a theme.changed envelope (shell → napplet push) to every live authenticated session whose frozen environment grants theme and whose current ACL grants theme:read. Stale or ineligible sessions are skipped before origin-registry delivery; recipient code is not trusted to enforce host authorization.

      Parameters

      • theme: Theme

        The new theme payload to broadcast.

      Returns void

      bridge.publishTheme({
        colors: { background: '#0a0a0a', text: '#e0e0e0', primary: '#7aa2f7' },
        title: 'Dark',
      });

    • Register a handler for consent requests on destructive signing kinds. Called when a napplet requests signing for kinds 0, 3, 5, or 10002.

      Parameters

      • handler: (request: ConsentRequest) => void

        Callback receiving the consent request with a resolve function

      Returns void

      bridge.registerConsentHandler((request) => {
        const allowed = confirm(`Allow signing kind ${request.event.kind}?`);
        request.resolve(allowed);
      });

    Settings

    Member Visibility

    On This Page

    Properties
    Methods