Kehto Runtime

Appearance

@kehto/runtime ​

Browser-agnostic protocol engine for NIP-5D napplet hosting.

Alpha status: Kehto is an early runtime toolkit for a draft NIP-5D protocol. Runtime APIs and NAP dispatch contracts are not final.

Install ​

bash
pnpm add @kehto/runtime @kehto/acl @napplet/core @napplet/nap

Manifest Facts ​

FieldValue
Sourcepackages/runtime/package.json, packages/runtime/src/index.ts
Version0.24.0
Runtime entry./dist/index.js
Types entry./dist/index.d.ts
Dependencies@kehto/acl, @noble/hashes, @noble/curves
Side effectsfalse

Peer Dependencies ​

PackageRange
@napplet/core>=0.32.0 <0.33.0
@napplet/nap>=0.32.0 <0.33.0

Primary APIs ​

AreaExports
FactorycreateRuntime, Runtime
Adapter typesRuntimeAdapter, SendToNapplet, RelayPoolAdapter, CacheAdapter, AuthAdapter, Signer, ConfigAdapter, HotkeyAdapter, CryptoAdapter, WindowManagerAdapter, RelayConfigAdapter, DmAdapter
EnforcementcreateEnforceGate, createNapEnforceGate, resolveCapabilitiesNap, formatDenialReason, EnforceResult, EnforceConfig, NapEnforceConfig, IdentityResolver, AclChecker, NapMessage
Session and manifestscreateSessionRegistry, createNappKeyRegistry, createManifestCache, SessionRegistry, NappKeyRegistry, ManifestCache
State and replaycreateAclState, handleStorageNap, cleanupNappState, createReplayDetector, createEventBuffer, matchesFilter, matchesAnyFilter, RING_BUFFER_SIZE
Service dispatchrouteServiceMessage, notifyServiceWindowDestroyed, ServiceHandler, ServiceRegistry, ServiceInfo
Re-exportsCapability, ALL_CAPABILITIES, ServiceDescriptor

Scope Boundaries ​

  • Owns message dispatch, ACL gates, service routing, storage handling, manifest cache, replay checks, and runtime lifecycle.
  • Follows draft NAP-RELAY PR #2 at 0be8abce18beb46ca37bd4ddd042f58d30b4eedc: relay.publish accepts an unsigned template, signs it through the shell-owned signer, publishes only the signed event, and returns canonical { ok, event, eventId } or { ok: false, error }. Async relay adapters settle before success is reported; failures are not buffered and release their pending replay reservation so the same deterministic signed event can be retried.
  • Passes the originating runtime window to AuthAdapter.getSigner(windowId?) when available. This is policy-neutral context for host runtimes; Kehto does not prescribe prompting, persistence, grant scope, or denial policy.
  • Routes the NAP-COUNT count.query domain through a registered count service. The runtime validates non-empty filters and returns count.query.result refusals such as invalid-filter or count-unavailable instead of emulating counts by fetching event payloads.
  • Keeps ACL and firewall rejection of outbox.query on the canonical outbox.query.result wire with the request id, events: [], and error, as defined by draft NAP-OUTBOX PR #32 at 4589a8f9a16d8aa29b3740e2b3b0cdca11e0976e.
  • Routes service-only NAP domains such as dm and fs through registered handlers, so protocol backends stay outside core runtime dispatch.
  • Does not own browser window, iframe creation, DOM, postMessage listeners, or localStorage implementation details.
  • Browser concerns live in @kehto/shell.

API Reference ​

Registration and initialization limits ​

Each trusted runtime.sessionRegistry.register(windowId, entry) starts a fresh initialization budget, even when a replacement iframe retains the logical window ID. Duplicate shell.ready messages do not re-register a live source, and neither request fields nor destroyWindow() alone reset the budget. The default startup guard still rejects operation 21 within three seconds; ordinary per-napplet rate limits remain shared across registrations and versions.

createSessionRegistry(notifier?, onRegister?) supports a host registration callback. The runtime wires it to firewallState.resetInitBudget(windowId), which retires only that startup counter. Custom FirewallStateContainer implementations must implement resetInitBudget(initKey) while preserving other counters and policy.

This is Kehto host policy, conformant with the source-bound, idempotent lifecycle in NAP-SHELL at a040914. It changes no NIP-5D wire messages or NAP-THEME result behavior.