Documentation
    Preparing search index...

    Interface Runtime

    The napplet protocol engine — handles NIP-5D NAP domain dispatch, ACL enforcement, subscription lifecycle.

    import { createRuntime } from '@kehto/runtime';

    const runtime = createRuntime(hooks);
    runtime.handleMessage('window-1', { type: 'relay.req', id: 'sub1', filters: [{ kinds: [1] }] });
    interface Runtime {
        aclState: AclStateContainer;
        legacyFirewall: LegacyFirewallAdapter | undefined;
        manifestCache: ManifestCache;
        permissions?: RuntimePermissions;
        sessionRegistry: SessionRegistry;
        destroy(): void;
        destroyWindow(windowId: string): void;
        getIncEndpointId(windowId: string): string | undefined;
        handleMessage(windowId: string, msg: unknown): void;
        hasService(name: string): boolean;
        injectEvent(topic: string, payload: unknown): void;
        registerConsentHandler(handler: ConsentHandler): void;
        registerService(name: string, handler: ServiceHandler): void;
        unregisterService(name: string): void;
    }
    Index

    Properties

    Access the ACL state container.

    legacyFirewall: LegacyFirewallAdapter | undefined

    Explicit legacy policy adapter, absent unless supplied by the host.

    manifestCache: ManifestCache

    Access the manifest cache.

    permissions?: RuntimePermissions

    Scoped permission management when the host supplies approval adapters.

    sessionRegistry: SessionRegistry

    Access the identity registry (for shell adapter to read napplet session state).

    Methods

    • Clean up all state associated with a napplet window. Removes subscriptions, pending state, and notifies service handlers. Services hear onWindowDestroyed at most once per session registration, even when sessionRegistry.unregister or a repeated call retires it too. With the permission runtime the source is retired; without it, a source that keeps dispatching is live again and its next destroy notifies.

      Parameters

      • windowId: string

        The window to clean up

      Returns void

    • Return the NAP-INC endpoint identifier of a live registered window.

      The identifier is opaque, runtime-assigned on first use, stable until that registration is replaced or unregistered, and never reused. It is the sender/peer other napplets see and the only valid inc.channel.open target. Handing it to another napplet is a host peer selection: do that only for a peer the host means to make addressable.

      Parameters

      • windowId: string

        Internal window identity of the registered napplet

      Returns string | undefined

      The endpoint identifier, or undefined without a live endpoint

      const target = runtime.getIncEndpointId('window-2');
      
    • Handle an incoming NIP-5D NappletMessage envelope from a napplet. The caller is responsible for identifying the source (windowId). Legacy NIP-01 arrays are silently dropped (clean break — no dual-mode).

      Parameters

      • windowId: string

        The identifier of the napplet that sent the message

      • msg: unknown

        The raw message (NappletMessage envelopes are processed; other types dropped)

      Returns void

    • Report whether this runtime currently routes an exact service domain.

      The runtime copies RuntimeAdapter.services once at creation, so a handler added to that object later is not routed until registerService() runs. Hosts read this before exposing a domain so advertisement cannot outrun routing.

      Parameters

      • name: string

        Exact domain name (e.g., 'webrtc')

      Returns boolean

      true while a handler is registered for the name

      runtime.registerService('webrtc', handler);
      runtime.hasService('webrtc'); // true
    • Inject a shell-originated event into subscription delivery.

      Parameters

      • topic: string

        The event topic tag value

      • payload: unknown

        The event content

      Returns void

    • Register a service handler dynamically after runtime creation. If a handler is already registered for this name, it is replaced.

      Built-in domains keep their NAP routing. Other domains require the handler's exact messageCapabilities map and an explicit host domain grant. Registration never injects namespace bindings or grants capabilities.

      Parameters

      • name: string

        Exact domain name (e.g., 'notify' or a host extension)

      • handler: ServiceHandler

        The service handler implementation

      Returns void

    • Unregister a service handler by name. No-op if the name is not registered.

      Parameters

      • name: string

        Service name to remove

      Returns void