Appearance
@kehto/runtime
Relay approval boundary
Relay requests create an immutable destination plan before approval. Registered services use RelayPlanningServiceHandler; direct adapters use subscribeToRelays() and publishToRelays(). Approval encloses buffer/cache delivery, encryption, signing, and transport. See compatibility for the retained legacy diagnostics.
Network relay hints require RuntimeAdapter.permissions. The runtime validates WebSocket URLs and presents canonical origins to relay.network approval before any transport. Hint URLs, filters and mutable host plans cannot change while a subscription waits for approval. Unhinted legacy network routing warns once per runtime with FW-RELAY-NETWORK-LEGACY-001; local-only reads remain quiet.
Scoped approvals are available through RuntimeAdapter.permissions, source-bound SessionEntry.permissionPrincipal, and ServiceRuntimeContext.authorizeOperation. The reference LINK service and declared extension routes are integrated; other service scope migration is ongoing. runtime.permissions.admit and isAdmissionCurrent support pre-execution interface approval; built-in interface dispatch requires the resulting grants. Prompt budgets are independently blocking. See the approval guide for storage, cancellation, revocation, and independent rate-budget contracts.
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/napManifest Facts
| Field | Value |
|---|---|
| Source | packages/runtime/package.json, packages/runtime/src/index.ts |
| Version | 0.31.1 |
| Runtime entry | ./dist/index.js |
| Types entry | ./dist/index.d.ts |
| Dependencies | @kehto/acl, @noble/hashes, @noble/curves |
| Side effects | false |
Peer Dependencies
| Package | Range |
|---|---|
@napplet/core | >=0.32.0 <0.46.0 |
@napplet/nap | >=0.32.0 <0.46.0 |
Primary APIs
| Area | Exports |
|---|---|
| Factory | createRuntime, Runtime |
| Adapter types | RuntimeAdapter, SendToNapplet, RelayPoolAdapter, CacheAdapter, AuthAdapter, Signer, ConfigAdapter, HotkeyAdapter, CryptoAdapter, WindowManagerAdapter, RelayConfigAdapter, DmAdapter |
| Enforcement | createEnforceGate, createNapEnforceGate, resolveCapabilitiesNap, formatDenialReason, EnforceResult, EnforceConfig, NapEnforceConfig, IdentityResolver, AclChecker, NapMessage |
| Session and manifests | createSessionRegistry, createNappKeyRegistry, createManifestCache, SessionRegistry, NappKeyRegistry, ManifestCache |
| State and replay | createAclState, handleStorageNap, cleanupNappState, createReplayDetector, createEventBuffer, matchesFilter, matchesAnyFilter, RING_BUFFER_SIZE |
| Service dispatch | routeServiceMessage, notifyServiceWindowDestroyed, ServiceHandler, ServiceRegistry, ServiceInfo |
| Unrecognized types | createUnrecognizedTypeDiagnostic, KEHTO_UNRECOGNIZED_MESSAGE_TYPE, UNRECOGNIZED_TYPE_WARNING_LIMIT, IgnoreUnrecognizedType, UnrecognizedTypeDiagnosticOptions |
| Re-exports | Capability, ALL_CAPABILITIES, ServiceDescriptor |
Scope Boundaries
Owns message dispatch, ACL gates, service routing, storage handling, manifest cache, replay checks, and runtime lifecycle.
Owns NAP-INC routing and endpoint identity.
sender,peer, andinc.channel.opentargetare opaque runtime-assigned endpoint identifiers, one per live registration and never a manifestdtag, per NAP-INC at377bf939c6c906817084b43dd21d424de646dbc2.runtime.getIncEndpointId(windowId)is the host's peer-selection lookup. Adtag target is rejected (KEHTO_INC_DTAG_TARGET_RETIREDin the compatibility register).aclState.setStateQuota(pubkey, dTag, aggregateHash, bytes)updates the live principal-scoped storage quota without changing grants, blocking, or stored data. Accepts safe integer byte counts from zero throughNumber.MAX_SAFE_INTEGER; invalid input throwsRangeErrorbefore mutation. Save withpersist(). Storage enforcement counts UTF-8 bytes including scoped keys; reducing the quota does not evict values. This host API conforms to NAP-STORAGE draft #3 at4f4cf0ca7ecbd24c284a5d63bcd85e3de6af37ca.Optional host-owned limiters implement
TemporalPolicy; runtime never imports their implementation. See Independent rate limits below for explicit setup.PermissionAdapter.defaultDecision(request, missing)answers a request no stored decision covers without prompting:allowadmits it without writing a grant, so a default allow can't fill the grant table (kehto/web#513);denyrefuses,askprompts. Stored denials, the ACL ceiling and operation budgets still apply. After changing rules, callRuntimePermissions.rulesChanged()to close live work admitted under the old ones.DEFAULT_RULE_GRANT_PREFIXis deprecated (DEFAULT_RULE_GRANTSin docs/compatibility.md). The rule model (createPermissionRules,resolvePermissionRule,setPermissionRule) is re-exported from@kehto/firewall.ACL listing and lookup return
AclEntryExternalwith requireddTagandaggregateHashfields. Feed those fields into keyed revoke/block/quota methods; listingpubkeyremains empty because it is not the principal key. Results are detached copies, remain identifiable after reload, and preserve existing serialized keys. Custom producers must provide the two identity fields.RuntimeAdapter.aclDefaultPolicysets the policy for identities with no stored entry.'restrictive'starts them with nothing granted. When it's omitted, the policy is'permissive'unless persisted ACL state stores another one. When it's set, it replaces the policy in persisted state on load, so an earlier permissive save can't reopen a restrictive host. Stored entries are kept as they are, so a host moving to'restrictive'should clear entries it no longer trusts. WithRuntimeAdapter.permissionsit's a ceiling: admission can still approve an interface, but an operation the ACL denies is refused with no prompt until the host grants the capability.ACL mutations and revoke/block observers take effect in memory before an explicit save.
aclState.persist()andaclState.clear()returntruewhen their synchronous backend call succeeds andfalsewhen it throws. Failure retains the live change; reload can still restore the prior durable policy. Check the result and retry after correcting storage.clear()resets live state to the configured default even when its backend call fails. Runtime teardown remains best-effort. This is host API policy, outside the NAP wire.Revoking
relay:reador blocking a principal retires ordinary relay subscriptions across its exactdTagand aggregate hash, closes service/adapter backends, and sendsrelay.closedwith reasondenied: relay:read. Events and EOSE queued by retired subscriptions remain suppressed after regrant andsubIdreuse. This host policy conforms to NAP-RELAY draft PR #2 at9f30b3505335a52c574ff570576687d6467021ff.A relay that throws while an approved
relay.subscribe,relay.publish,relay.publishEncrypted, orrelay.queryruns reports a transport reason (relay subscription failed,publish failed,relay query failed). Only an approval that was denied or cancelled keepsrelay authorization unavailable or denied; a full approval queue or rate limit isapproval busyand a missing prompt UI or failed grant store isapproval unavailable. A subscription that fails after it opened is retired, so no event or EOSE follows itsrelay.closed. NAP-RELAY reasons are free-form, so only that split is fixed.PermissionAdapter.maxRequirements,maxGrantsandmaxGrantsPerPrincipalset the Firewall bounds (validated bypermissionLimitswhen the runtime starts); services read the first asServiceRuntimeContext.maxPermissionRequirements. A full grant table returns thecapacityapproval outcome, which relay reports asapproval capacity reached, never a denial.Relay approval names each relay origin once. A host relay plan spanning more origins than one Firewall request can carry (
maxRequirements, defaultMAX_PERMISSION_REQUIREMENTS) fails withtoo many relaysinstead of a denial; NAP-RELAY lets the shell terminate a subscription for a resource limit. Hosts withoutRuntimeAdapter.permissionsare unchanged.Follows draft NAP-RELAY PR #2 at
0be8abce18beb46ca37bd4ddd042f58d30b4eedc:relay.publishaccepts 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.querydomain through a registeredcountservice. The runtime validates non-empty filters and returnscount.query.resultrefusals such asinvalid-filterorcount-unavailableinstead of emulating counts by fetching event payloads.Keeps ACL and firewall rejection of
outbox.queryon the canonicaloutbox.query.resultwire with the requestid,events: [], anderror, as defined by draft NAP-OUTBOX PR #32 at4589a8f9a16d8aa29b3740e2b3b0cdca11e0976e.Routes service-only NAP domains such as
dmandfsthrough registered handlers, so protocol backends stay outside core runtime dispatch.Does not own browser
window, iframe creation, DOM,postMessagelisteners, or localStorage implementation details.Browser concerns live in
@kehto/shell.
ACL denial wires
ACL and legacy Firewall denials answer each recognized request on its owning NAP's failure wire, never an invented <type>.error. A denied cvm.* request gets its matching .result with error: "policy denied" (NAP-CVM #31 at 28cf1bdb); relay, outbox, upload, count, notify, dm, fs, keys, media and config follow their own NAPs, and requests with no defined reply stay silent (including a denied config.get). The legacy Firewall gate uses the same rows for common, lists, serial, ble, webrtc, link and gamepad, which ACL does not gate. A denied type that its NAP does not define as a napplet request gets no reply in any domain. The per-type table, refs and spec-gap decisions are in RUNTIME-SPEC.md.
Registered extension routing
Outside the built-in NAP domains, a service needs an exact ServiceHandler.messageCapabilities map and an explicit isDomainAllowed grant. Each inbound type maps to an existing ACL capability or explicit null. The runtime checks the live source, block state, declared ACL requirement, and firewall before delivery. Unknown types are silent; denial does not invent an extension error envelope. Static and dynamic registration follow the same path. Pending replies remain bound to that registration and source lifecycle and recheck current domain/ACL policy. Built-in NAP routing retains its own contracts. Shell -> napplet pushes into a custom domain require an exact ServiceHandler.pushCapabilities map and go through ServiceRuntimeContext.sendToEligibleNapplet, which applies the same source, domain-grant, and ACL gates and returns whether the push was delivered.
When a registered relay service accepts a relay.publish, that service owns storage and fan-out of the event (publisher echo, per-subscription relay scope); the runtime ring buffer only fans out publishes it coordinates itself through the adapter relay pool.
Registration is not namespace injection or capability authorization. The host owns the extension's protocol and, for browsers, its pre-execution binding. routeServiceMessage bypasses policy and must not handle untrusted ingress. See Register a service for examples, lifecycle rules, and specification bounds.
API Reference
Service registry snapshot
createRuntime() copies RuntimeAdapter.services once. Later changes go through registerService() and unregisterService(), which also run onRegistered and onUnregistered and bind the permission context; the runtime never writes to the host's services object. hasService(name) reports what is routed right now, and @kehto/shell uses it to keep advertisement in step with routing.
A request for a service-only domain with no handler is dropped without a reply: NIP-5D at f60550c requires unrecognized types to be silently ignored. The runtime logs [KEHTO_UNROUTED_SERVICE_DOMAIN] once per domain per runtime, naming the domain only. See Services that arrive late.
Unrecognized message types
A type that the owning NAP does not define gets no reply from any runtime handler, from any @kehto/services reference service, or through the ACL/firewall denial path. This holds even when a capability would be denied, because NIP-5D says "Unrecognized message types are silently ignored, preventing capability probing." A known type with a malformed payload still gets its NAP's failure result.
createUnrecognizedTypeDiagnostic() gives a service the matching host-side diagnostic. Call it once per service instance, drop the message, and call the returned function with your domain and the incoming type:
ts
import { createUnrecognizedTypeDiagnostic } from '@kehto/runtime';
const ignoreUnrecognized = createUnrecognizedTypeDiagnostic();
// inside handleMessage, after the known types:
ignoreUnrecognized('serial', message.type); // no replyIt logs [KEHTO_UNRECOGNIZED_MESSAGE_TYPE] once per domain/type, for at most UNRECOGNIZED_TYPE_WARNING_LIMIT (16) types per instance, then goes quiet. It prints the type only when it is a plain domain.action string of up to 64 characters, and never logs payloads or ids. Pass { warn } to send it elsewhere.
Registration and initialization limits
sessionRegistry.unregister(windowId) removes registration and lookup state for that window, including the empty-pubkey NIP-5D path, and clears its pending update. It is idempotent and preserves a newer window's lookup when both share a pubkey. Use getEntryByWindowId for per-window identity in that case.
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. An explicitly installed legacy adapter using its suggested startup guard 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. When a legacy adapter is explicitly installed, runtime calls its 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.
Window destroy notifications
A retirement can reach the runtime through several teardown calls: destroyWindow(windowId), sessionRegistry.unregister(windowId) (which notifies services when the permission runtime is installed), and a shell bridge revoke that runs both again. Services hear onWindowDestroyed at most once per session registration, whichever call comes first. A later register() of the same window ID is a new lifetime with its own destroy, and replacing a live registration with the permission runtime installed retires the old one once. With the permission runtime, destroyWindow() also retires the source, so it dispatches nothing more. Without it, a source that keeps sending messages after a cleanup destroyWindow() is live again, and its next destroy notifies services, so state it gathered in between is still cleaned. A window ID with no tracked registration has nothing to deduplicate against, so each destroyWindow() call for it is broadcast. Permission revocation stays separate: onPermissionRevoked (or its onWindowDestroyed fallback for handlers without it) never consumes the registration's destroy. The exported notifyServiceWindowDestroyed() helper is a raw broadcaster and does not deduplicate. It changes no NIP-5D or NAP wire messages.
- Generated module:
docs/api/modules/_kehto_runtime.html
GAMEPAD integration
This non-normative guidance defers to the living NAP-GAMEPAD. Services export createGamepadService and browserGamepadOptions; shell exports denyNappletControllerAccess. Paja registers one host reader and denies native gamepad/HID/USB paths before frame execution. Source-bound subscriptions receive immediate full snapshots; only the visible host's input owner gets live controls. Focus loss supplies neutral controls and timestamp zero; unsubscribe, window destruction, and service removal release polling. Non-browser or denied native readers report the proposal's unavailable reasons. See Controller input.
LLM integration
This non-normative guidance defers to the living NAP-LLM (checked at 5e93bdf). Services export createLlmService, LlmServiceError, the provider mappers (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages and Gemini generateContent dialects) and LLM_PROVIDER_PRESETS; shell exports getShellDomainState and the LlmHooks adapter field; acl exports llm:generate. The runtime routes llm.* to one registered service and answers every sanctioned request with exactly one llm.<op>.result, shaping missing-service and ACL failures as { code: 'unsupported' }. Hosts implement LlmConnectionHost; the service enforces schema, handle ownership, a per-window live-handle bound (maxHandlesPerWindow), consent before submission, duplicate ids, cancellation and deadline races, ordered deltas and safe errors, and passes select/authorize a { signal } that withdraws stale prompts. createHttpLlmProvider({ stream: true }) streams provider output into llm.delta as block start/delta/end events. Results carry content parts (text, thinking and tool calls); tool calls and results are validated and relayed, and Kehto never executes one. Advertisement stays binary on the wire while hosts report a third unconfigured state until the user adds a connection. See Language models.
Media sessions
See Media playback for NAP-MEDIA draft authority, shell-owned audio/video, shared host controls, endpoint cleanup, and command API migration.
Independent rate limits
Rate limiting is optional and lives in @kehto/rate-limit, not runtime or Firewall. Supply PermissionAdapter.rateLimiter and/or promptRateLimiter to opt in; omitting either installs no default counters or limits for that traffic.
ts
import { createRateLimiter, defaultRateLimitConfig } from '@kehto/rate-limit';
const limiter = createRateLimiter(defaultRateLimitConfig());
const permissions = { ...approvalAdapter, rateLimiter: limiter };
limiter.setConfig({ ...limiter.config, unfocusedMultiplier: 0.5 });Hold the limiter to inspect config or call setConfig, which validates without resetting counters. Runtime passes trusted identity/lifecycle observations and retires lifecycle counters on teardown. Approval, ACL and source checks remain independent. Without scoped permissions, hosts may explicitly install legacyFirewall from @kehto/rate-limit/legacy; the default installs neither.
Cancelling one approved operation
Services may pass a request-owned signal as the fifth argument to ServiceRuntimeContext.authorizeOperation(windowId, operation, requirements, execute, signal). Aborting it settles that request as cancelled, dismisses its prompt through the prompt signal, and aborts the signal passed to execute. Sibling requests keep their own lifetimes. Late approval answers cannot create grants; late action results are discarded. The service must still observe the execution signal before each later side effect and apply its protocol's cancellation response rules.
A cancelled queued request settles immediately, but later equivalent requests still wait behind the active prompt. Retained queue entries count toward the queue bound until their predecessor settles. Request listeners are removed when the operation settles. An already-aborted signal never opens a prompt or invokes the action.
Registered extensions revalidate their exact capability declaration after approval and before sending deferred replies. Replacing, removing, or changing that declaration invalidates the captured operation; a late answer grants nothing.