Documentation
    Preparing search index...

    Interface RuntimeAdapter

    All adapters that the runtime requires from the host environment.

    This is the primary integration point. A browser shell implements these by wrapping postMessage, localStorage, and relay pool libraries. A CLI or server shell could implement them with host bridge channels, file storage, and direct WebSocket connections.

    import { createRuntime, type RuntimeAdapter } from '@kehto/runtime';

    const hooks: RuntimeAdapter = {
      sendToNapplet: (wid, msg) => iframeWindows.get(wid)?.postMessage(msg, '*'),
      relayPool: myRelayPoolAdapter,
      cache: myCacheAdapter,
      auth: myAuthAdapter,
      config: myConfigAdapter,
      hotkeys: myHotkeyAdapter,
      crypto: myCryptoAdapter,
      aclPersistence: myAclPersistenceAdapter,
      manifestPersistence: myManifestPersistenceAdapter,
      statePersistence: myStatePersistenceAdapter,
      windowManager: myWindowManagerAdapter,
      relayConfig: myRelayConfigAdapter,
    };

    const runtime = createRuntime(hooks);
    interface RuntimeAdapter {
        aclPersistence: AclPersistence;
        auth: AuthAdapter;
        cache?: CacheAdapter;
        config: ConfigAdapter;
        crypto: CryptoAdapter;
        dm?: DmAdapter;
        firewallPersistence?: FirewallPersistence;
        getFocusContext?: (
            windowId: string,
        ) => { focused: boolean; msSinceFocusGain?: number };
        guidPersistence?: GuidPersistence;
        hashVerifier?: HashVerifierAdapter;
        hotkeys: HotkeyAdapter;
        manifestPersistence: ManifestPersistence;
        onAclCheck?: (event: AclCheckEvent) => void;
        onCompatibilityIssue?: (report: CompatibilityReport) => void;
        onFirewallEvent?: (event: FirewallEvent) => void;
        onHashMismatch?: (dTag: string, claimed: string, computed: string) => void;
        onPendingUpdate?: PendingUpdateNotifier;
        relayConfig: RelayConfigAdapter;
        relayPool?: RelayPoolAdapter;
        sendToNapplet: SendToNapplet;
        services?: ServiceRegistry;
        shellSecretPersistence?: ShellSecretPersistence;
        statePersistence: StatePersistence;
        strictMode?: boolean;
        windowManager: WindowManagerAdapter;
        getConfigOverrides?(): RuntimeConfigOverrides;
    }
    Index

    Properties

    aclPersistence auth cache? config crypto dm? firewallPersistence? getFocusContext? guidPersistence? hashVerifier? hotkeys manifestPersistence onAclCheck? onCompatibilityIssue? onFirewallEvent? onHashMismatch? onPendingUpdate? relayConfig relayPool? sendToNapplet services? shellSecretPersistence? statePersistence strictMode? windowManager

    Methods

    getConfigOverrides?

    Properties

    aclPersistence: AclPersistence

    ACL persistence (save/load ACL state).

    auth: AuthAdapter

    Auth state and signing.

    NIP-5D path: getUserPubkey() provides the shell user's identity (not napplet's). getSigner() is the primary concern — used for proxied signing operations from napplets.

    cache?: CacheAdapter

    Local event cache (worker relay). Optional when a 'cache' or 'relay' (coordinated) service is registered. If neither adapter nor service are provided, cache functionality is unavailable.

    config: ConfigAdapter

    Runtime configuration.

    crypto: CryptoAdapter

    Crypto operations (signature verification, random UUID).

    dm?: DmAdapter

    DM sending (optional).

    firewallPersistence?: FirewallPersistence

    Firewall config persistence (save/load firewall config). When absent, firewall config is in-memory only and resets on reload. Only the config is persisted; ephemeral counters are never stored.

    getFocusContext?: (
        windowId: string,
    ) => { focused: boolean; msSinceFocusGain?: number }

    Returns the current focus state for a napplet window. When absent, defaults to { focused: true } — a host without a window manager treats everything as focused, so focus never tightens rate budgets. Focus alone never hard-blocks; it only scales token refill rates.

    Type Declaration

      • (windowId: string): { focused: boolean; msSinceFocusGain?: number }

      • Parameters

        • windowId: string

          The napplet window to query focus state for.

        Returns { focused: boolean; msSinceFocusGain?: number }

        Current focus state and optional milliseconds since last focus gain.

    guidPersistence?: GuidPersistence

    GUID persistence for iframe instance tracking (optional — if absent, GUIDs are in-memory only).

    hashVerifier?: HashVerifierAdapter

    Hash verification (optional — if absent, hash verification is skipped).

    hotkeys: HotkeyAdapter

    Hotkey dispatch.

    manifestPersistence: ManifestPersistence

    Manifest cache persistence.

    onAclCheck?: (event: AclCheckEvent) => void

    Called on every ACL enforcement check (audit).

    onCompatibilityIssue?: (report: CompatibilityReport) => void

    Called when a napplet's required services are not fully available. Receives a CompatibilityReport with available/missing services. In strict mode, the runtime blocks the napplet from loading. In permissive mode (default), the napplet loads and the host decides UX.

    onFirewallEvent?: (event: FirewallEvent) => void

    Called on every firewall evaluation that results in an audit-level decision (flag, block, or prompt). When absent, firewall decisions are not audited.

    onHashMismatch?: (dTag: string, claimed: string, computed: string) => void

    Called when aggregate hash verification fails (computed != declared). Host app should display a user-visible warning.

    onPendingUpdate?: PendingUpdateNotifier

    Called when a pending napp update is set or cleared.

    relayConfig: RelayConfigAdapter

    Relay configuration.

    relayPool?: RelayPoolAdapter

    Relay pool operations. Optional when a 'relay' or 'relay-pool' service is registered via RuntimeAdapter.services or runtime.registerService(). If neither adapter nor service are provided, relay functionality is unavailable.

    sendToNapplet: SendToNapplet

    Send a NIP-01 message to a napplet by windowId.

    services?: ServiceRegistry

    Optional service extensions. Shell/host registers service handlers here for static initialization. Services can also be added dynamically via runtime.registerService(). Each key is a service name (e.g., 'audio').

    const hooks: RuntimeAdapter = {
      // ... required adapters ...
      services: {
        audio: myAudioServiceHandler,
      },
    };
    shellSecretPersistence?: ShellSecretPersistence

    Shell secret persistence (for deterministic keypair derivation).

    NIP-5D: Shell secrets are no longer needed when using the NIP-5D origin-based identity path. Kept for backward compatibility with legacy AUTH sessions.

    statePersistence: StatePersistence

    Napplet state storage.

    strictMode?: boolean

    When true, missing required services block napplet loading. When false or omitted (default), napplets load with a warning.

    windowManager: WindowManagerAdapter

    Window management.

    Methods

    Settings

    Member Visibility

    On This Page

    Properties
    Methods