Documentation
    Preparing search index...

    Interface ShellBridge

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

    NIP-5D binds napplet identity to a MessagePort, not to the iframe Window: the injected bootstrap transfers one port to the shell in a single window-level napplet.hello. The bridge accepts that hello only from the contentWindow of a registered iframe carrying exactly one port, binds the frame's verified (dTag, aggregateHash) to the port, and then processes NAP envelopes only from that port and replies only over it. A second hello, any other window-level message, an invalid hello, a second iframe load (ShellBridge.observeFrame) or the port closing revokes the binding, its sessions and grants, and asks the host to remove the frame through ShellAdapter.onNappletRevoked. 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;
        observeFrame(
            frame: Pick<
                HTMLIFrameElement,
                "addEventListener"
                | "removeEventListener",
            >,
            windowId: string,
            options?: NappletFrameObservation,
        ): () => void;
        publishIdentityChanged(pubkey: string): void;
        publishTheme(theme: Theme): void;
        registerConsentHandler(handler: (request: ConsentRequest) => void): void;
        releaseDeferred(windowId: string): number;
        revokeNapplet(windowId: string, reason?: NappletRevocationReason): void;
    }
    Index

    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 a window-level message from a napplet iframe.

      The only window-level message a napplet may send is its single napplet.hello carrying exactly one MessagePort. The bridge binds that port and receives every later NAP envelope from it. Any other window-level message from a registered iframe, a second hello, or a hello without exactly one port revokes the frame. Messages from unregistered sources are dropped.

      On the bound port, only NIP-5D envelope objects (plain objects with a .type string) are accepted. shell.ready is handled locally (the bridge answers with shell.init over the port); 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 });
      
    • Watch a napplet iframe for a second load, which NIP-5D treats as evidence that the verified document was replaced. Call after the frame is in the DOM and before assigning its srcdoc/src.

      Under the experimental nested-context lock it also revokes the binding (nested-context) when the frame's Window holds a child browsing context, checked on load and on each envelope from the bound port. Admission marks locked documents itself; pass { nestedContextLock: true } when the host prepared the srcdoc with prepareNappletSrcdoc instead.

      Parameters

      • frame: Pick<HTMLIFrameElement, "addEventListener" | "removeEventListener">

        The shell-created napplet iframe

      • windowId: string

        The windowId registered for this frame

      • Optionaloptions: NappletFrameObservation

        Whether the frame runs under the nested-context lock

      Returns () => void

      A function that stops watching

      document.body.append(frame);
      originRegistry.register(frame.contentWindow!, windowId, identity);
      const stop = bridge.observeFrame(frame, windowId);
      frame.srcdoc = verifiedSrcdoc;
    • 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);
      });
    • Dispatch the envelopes ShellAdapter.filterNappletMessage deferred for a window, in arrival order and without asking the filter again. ACL, firewall approvals and budgets run at release, so held requests can prompt or be refused then, and a source retired meanwhile runs nothing. Revoking a binding discards what it held.

      Parameters

      • windowId: string

        The napplet window to release

      Returns number

      How many envelopes were dispatched

      bridge.releaseDeferred(windowId);
      
    • Revoke one napplet binding: close its port, unregister it, destroy its sessions and subscriptions, and call ShellAdapter.onNappletRevoked so the host removes the frame. No-op for unknown windows.

      Parameters

      • windowId: string

        The window to revoke

      • Optionalreason: NappletRevocationReason

        Why the binding is revoked (defaults to host)

      Returns void

      bridge.revokeNapplet(windowId);