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 = {
    // NIP-5D: send over the port bound by the napplet's napplet.hello.
    sendToNapplet: (wid, msg) => helloPorts.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 {
        aclDefaultPolicy?: "permissive" | "restrictive";
        aclPersistence: AclPersistence;
        auth: AuthAdapter;
        cache?: CacheAdapter;
        config: ConfigAdapter;
        crypto: CryptoAdapter;
        dm?: DmAdapter;
        getFocusContext?: (
            windowId: string,
        ) => { focused: boolean; msSinceFocusGain?: number };
        guidPersistence?: GuidPersistence;
        hashVerifier?: HashVerifierAdapter;
        hotkeys: HotkeyAdapter;
        isDomainAllowed?: (windowId: string, domain: string) => boolean;
        legacyFirewall?: LegacyFirewallAdapter;
        manifestPersistence: ManifestPersistence;
        onAclCheck?: (event: AclCheckEvent) => void;
        onCompatibilityIssue?: (report: CompatibilityReport) => void;
        onFirewallEvent?: (event: FirewallEvent) => void;
        onHashMismatch?: (dTag: string, claimed: string, computed: string) => void;
        onPendingUpdate?: PendingUpdateNotifier;
        permissions?: PermissionAdapter;
        relayConfig: RelayConfigAdapter;
        relayPool?: RelayPoolAdapter;
        sendToNapplet: SendToNapplet;
        services?: ServiceRegistry;
        shellSecretPersistence?: ShellSecretPersistence;
        statePersistence: StatePersistence;
        strictMode?: boolean;
        windowManager: WindowManagerAdapter;
        getConfigOverrides?(): RuntimeConfigOverrides;
    }
    Index

    Properties

    aclDefaultPolicy?: "permissive" | "restrictive"

    ACL policy for identities with no stored entry. When omitted, 'permissive' unless persisted state stores another. When set, it replaces the persisted policy on load and keeps stored entries. With permissions set it's a ceiling: an approval can't exceed what the ACL denies, and no prompt is shown for it.

    aclPersistence: AclPersistence

    ACL persistence (save/load ACL state).

    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.

    Runtime configuration.

    Crypto operations (signature verification, random UUID).

    DM sending (optional).

    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.

    isDomainAllowed?: (windowId: string, domain: string) => boolean

    Determines whether a session-established napplet may invoke a NAP domain. Built-in routes remain eligible when omitted; extension routes require an explicit true result. Browser shells must derive this decision from the source-bound namespace exposed before napplet scripts execute.

    legacyFirewall?: LegacyFirewallAdapter

    Explicit legacy behavioral adapter from @kehto/rate-limit/legacy. When absent, no legacy temporal controls are installed. Only the config is persisted; ephemeral counters are never stored. Legacy gate only: with permissions set, use permissions.persistence.

    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. Legacy gate only: with permissions set, use permissions.onRateLimit.

    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.

    permissions?: PermissionAdapter

    Scoped approval adapters. Hosts migrate together with source principal registration.

    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. The runtime copies this object once at creation; a handler added to it later is not routed. Add or remove services afterwards with runtime.registerService() and runtime.unregisterService(). Keys select exact domains (e.g., 'notify'). Outside built-in domains, handlers also need messageCapabilities and an explicit isDomainAllowed grant. Hosts own each extension's NAP contract, payload validation, and pre-execution browser namespace binding.

    const hooks: RuntimeAdapter = {
    // ... required adapters ...
    services: {
    notify: myNotificationServiceHandler,
    },
    };
    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