npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@kehto/services

v0.36.0

Published

Reference service implementations for the napplet protocol — notifications and extensible service handlers

Readme

@kehto/services

Relay hints are candidates, not authority. Register relay services through a runtime with RuntimeAdapter.permissions; execute only its approved plan. Standalone OUTBOX requests with nonempty options.relays now fail before router execution. Unhinted standalone calls retain FW-OUTBOX-LEGACY-001 during migration. Planned OUTBOX publishing receives the operation cancellation signal and checks it again after signing, so revocation while signing waits prevents transport. The plan includes the complete own-outbox, required inbox and explicit relay union. Host-only requiredRelays metadata prevents optional hint success from masking failure of a required destination. Custom planners must supply that metadata for own/inbox fanout; incomplete plans fail before signing. The concrete OUTBOX router validates WebSocket URLs and defaults to rejecting unconfigured local/private literals and names. Explicit host fallback relays and the host's isRelayAllowed policy can admit development destinations; credentials, fragments and malformed URLs are always rejected. Adapters still need DNS-time address checks to prevent rebinding. See relay destination policy.

createLinkService uses ServiceRuntimeContext.authorizeOperation when attached to a runtime with approval adapters. It requires both interface and exact URL scopes, preserves request IDs in canonical results, rejects forbidden local/code schemes, and drops retired-source results. The temporary host-only opener path warns once per service instance (FW-LINK-LEGACY-001). See scoped approvals and compatibility for migration details.

Reference service handlers for the napplet protocol — identity, relay pool, cache, keys, media, notify, theme, link, common, lists, serial, BLE, WebRTC, and DM.

Alpha status: Kehto is an early runtime toolkit for a draft NIP-5D protocol. NAP contracts and service envelopes are not final; treat these handlers as reference implementations for the current draft.

ContextVM transport limits

The Nostr transport accepts integer request durations from 1 through 300,000ms (default 30,000ms). Malformed or out-of-range values fail with invalid timeout before session acquisition or publication. One deadline covers initialization, waiting for shared initialization, initialized-notification publication, and the final response; expiry returns relay timeout. Progress never resets it. Inbound CEP-22 buffers live for at most the remaining request budget, bounded by min(request timeout, 300_000), including time already spent initializing. CEP-41 close with unresolved chunk gaps fails immediately, whether or not lastChunkIndex is present. Contiguous buffered chunks drain when the missing predecessor arrives before close. The transport does not wait for a post-close grace period or report successful closure while dropping gaps.

Outbound oversized requests are not split into CEP-22 frames. With encryption enabled, tool arguments must fit one NIP-44 plaintext message. The transport does not know the calling napplet and does not cap its pending request map; createCvmService admits work per endpoint before invoking it. Frame caps are not a substitute for that admission. Transport sessions and relay holds remain until close(server) or dispose(), independently of request expiry.

createCvmService({ transport, concurrency: { maxInFlight, maxQueued } }) gives each authenticated endpoint its own budget (defaults: 8 running, 32 queued). Every cvm.discover, cvm.request, and cvm.registry.* envelope holds one slot from receipt until it settles. Queued time counts against the request deadline (relay timeout), overflow is refused with policy denied, and slots return on result, error, timeout, cvm.close, revocation, window destroy, and disposal. One endpoint filling its budget never delays another. Correlation IDs and ping nonces use random bytes plus counters, without per-ID key derivation.

Authority: NAP-CVM draft #31 and CEP-41. createCvmService({ transport, registry }) optionally accepts host-configured CvmRegistryFamily entries with a provider and tool name/hash pins. Selector, entry and option types are re-exported from @napplet/core (>= 0.42.0). Registry selection checks live tools/list schemas using computeCvmToolSchemaHash (CEP-15), honors provider pins, and authorizes calls through the ordinary CVM boundary. Without registry configuration, registry.has returns false and the other registry operations return unsupported method. Paginated tool inventories are currently rejected; no result cache or automatic provider failover is used.

cvm.request checks its MCP message against the NAP-CVM request, notification and response forms before admission; a missing message, batch, invalid id or invalid field combination returns invalid message and is never published. Notifications and responses complete on publication with a result that has only type and id, through the optional CvmTransport.publish() (transports without it fall back to request() and warn once, KEHTO_CVM_TRANSPORT_PUBLISH). A reused client request id or a response matching no delivered server request is invalid message, and a malformed server is invalid request. A server request delivered to a napplet expires after serverRequestTimeoutMs (default 30000, at most 300000); a later response is invalid message. A notifications/cancelled must name one of the napplet's own requests: a queued or pending-approval one is dropped before publication; one already handed to the transport goes to the optional CvmTransport.cancel(), which maps its requestId to the id the transport sent (transports without it publish it unchanged and warn once, KEHTO_CVM_TRANSPORT_CANCEL). Either way the cancelled cvm.request settles with session closed before the cancellation's acknowledgement, and the cancellation takes no admission slot. A settled one is acknowledged without publication; anything else is invalid message.

These transport limits do not claim implementation of every newer NAP-CVM session or payment field.

Install

pnpm add @kehto/services

Published Napplet Compatibility

Peers admit @napplet/core >=0.42.0 <0.46.0 and @napplet/nap >=0.37.0 <0.46.0: the declarations import the packaged NAP-LLM types from @napplet/nap/llm/types, and the exported NAP-INTENT types come from @napplet/core, whose releases before 0.41.0 carry the withdrawn delivery ID and nullable sender. The exported NAP-CVM registry types (CvmRegistrySelector, CvmRegistryEntry, CvmRegistryTool, CvmRegistryOptions, CvmRegistryCallOptions, CvmRegistryQuery) also come from @napplet/core, and releases before 0.42.0 carry the older family-only registry contract, so the core floor is 0.42.0. Host packages develop and build on core 0.45.0 / nap 0.45.0; fixture napplets stay on the exact 0.32.0 line (shim 0.30.0, sdk 0.28.0, vite-plugin 0.16.2). The exact fixture-line contracts are core 0.32.0 / nap 0.32.0 from NAP-INTENT authority 5ac0490461ca6fec2f0d2e45b4835cf9bc08de24, napplet/web#199 source 3037200c932488f14f7f369b8583c39c9c16510a / merge b3f0007867eac109fa4917fac9c285d3b7cc6155, and Version Packages #198 release source dc1d24153c759152b6ba31a6ec9bea967798f2df.

Overview

@kehto/services ships the reference implementations of the ServiceHandler contract defined by @kehto/runtime. Each factory returns an object that the runtime routes NIP-5D envelopes to by the exact message.type domain (for example, notify.create goes to the handler registered under notify).

Host apps wire services into the runtime via runtime.registerService(name, handler). The services are browser-agnostic — they have no DOM dependency. Browser-specific behaviors (audio element pool, OS notifications) are delivered through host-supplied callbacks.

Services are selected only by the exact message.type domain. INC topics are opaque, queryless identities matched only by exact equality, so their text must not select a service handler. The runtime attaches the sender to delivered INC events from the authenticated endpoint; services do not create INC events.

Current draft posture:

  • The v1.1 signer service is deleted outright. Its responsibilities split into two: read-only identity lookups go through createIdentityService (getPublicKey, getRelays, getProfile, getFollows, getList, getZaps, getMutes, getBlocked, getBadges); signing happens inside the shell as part of relay.publish / relay.publishEncrypted and is never exposed to napplets.
  • createKeysService and createMediaService ship real reference backends as of v1.4 (see the dedicated sections below). createKeysService attaches a document-level keydown listener by default and delivers keys.action push envelopes to registered napplets; createMediaService mirrors session metadata and playback state to navigator.mediaSession and emits media.command push envelopes on OS transport events. Both accept a host-bridge option (HostKeysBridge / HostMediaBridge) so Electron / Tauri / native shells can swap in OS-level backends without re-implementing the wire-protocol bookkeeping.
  • createNotifyService handles direct notify.* envelopes. It is not an INC topic handler. A permission-enabled runtime approves notify.send and channel/badge effects before the host callback runs. Dismiss remains owner-only cleanup. createNotificationService retains the older notify.create/list/read registry as a deprecated compatibility path.
  • createOutboxService supports outbox.getEvent from draft NAP-OUTBOX. Single-event lookups run through shell-owned relay routing and only return events whose ID matches the request. Hosts can provide getReadRouter to scope all event-returning reads (getEvent, query, and subscription) to the authenticated source window, plus getQueryRouter when one-shot queries need an additional decorator. The draft wire contract keeps outbox.query one-shot and outbox.subscribe streaming; Kehto's concrete createRelayPoolOutboxRouter additionally exposes host-side queryStream() so verified query events can arrive before asynchronous NIP-65 discovery completes.
  • createResourceService implements NAP-RESOURCE at draft PR #80 head ae5b9c64ab8a4d8909f288829a01e99d6bd713bc without choosing a runtime's resolver policy. Single requests carry url; bulk requests carry an ordered urls array, and results use canonical padded RFC 4648 base64 in blob. resource.info.schemes remains advisory. Runtime permission integration authorizes the exact resource URL and each resolver-reported HTTP(S) or WebSocket origin through init.authorizeNetwork(destination, execute); the resolver remains responsible for scheme handling, redirects, and upstream byte classification. The service scopes cancellation to the requesting window, drops cancelled terminal envelopes, and preserves explicit ResourceServiceError codes.
  • Host playback can use ResourceService.openStream(windowId, url, signal) with an optional stream resolver. It requires the same resource and network approvals as atomic requests before opening a response; on a host without a permission adapter it takes the FW-RESOURCE-LEGACY-001 path. createBrowserMediaStreamFetch classifies live MP3/AAC bytes without waiting for EOF; createBrowserMediaPlayback({ resource, stream: resource.openStream }) supplies bounded MediaSource playback. Streaming is host-only and adds no resource wire operation. See Media playback.
  • createUploadService supports upload.info from draft NAP-UPLOAD. Hosts may expose configured rails, return URL forms, maximum bytes, and MIME type policy without requiring napplets to start an upload.
  • Default upload ids, browser media media-resource-* read ids, and CVM registry JSON-RPC ids are secure UUID v4 values: native crypto.randomUUID(), or 16 crypto.getRandomValues() bytes where the browser omits it (non-localhost plain HTTP), and an explicit error when neither exists. This is host identifier policy with no wire change, and it does not make crypto.subtle paths (approval-scoped uploads, the default HTTP uploader digest, CVM schema hashes) work on such origins. The full per-identifier contract is in the shell package doc.
  • Upload teardown uses exact window ownership, including IDs containing colons. Destroying a window invalidates replies before backend cancellation and suppresses late progress, results, and errors even if cancellation throws or settles later. Reusing a window/upload ID starts a new callback lifetime. Service removal invalidates all windows and cancels their tracked uploads. This host lifecycle policy follows NAP-UPLOAD draft #33 at f5cc981e527e2cc1572793a7a6e5082e5271ac49 without changing responses to live requesters.
  • createConfigService implements draft NAP-CONFIG's shell-writer boundary: recursive bounded-subset schema validation, per-window schema/subscription state, deterministic defaults, invalid/orphan removal, version rollback rejection, scoped host persistence hooks, and settings-UI commits. Reads before schema registration fail closed with no-schema.
  • createDmService keeps NAP-DM request correlation, per-window subscriptions, and packaged message shapes in runtime-owned code. Adapters cover concrete transports: verified NIP-17 gift wraps and relay history via nostr-tools, structural NDR runtimes with relay hooks, and Cordn/ContextVM coordinator clients.
  • createFsService keeps NAP-FS result correlation and per-window watch identity in runtime-owned code. An injected FsBackend owns real persistence, virtual-path policy, picker mediation, byte validation, revisions, mutations, and watch observation.

NAP-INTENT manifest resolver

Kehto follows NAP-INTENT PR #106 at fc121fc264615482143eda86125863d2e1f741a2. The shell binding normalizes URI calls into a queryless convention and separate opaque payload before service dispatch.

  • manifestToIntentCatalogEntry() converts verified { catalogId, title?, archetypes: [{ slug, convention, params }] } facts into exact contracts.
  • createCatalogIntentResolver() applies authorized explicit selection, an explicit chooser, or default → recommendation → compatible choice. Payload contents never select a handler.
  • offerUninstalledHandlers(request, context), which is optional, runs only when no installed handler is compatible and the request isn't for an explicit catalog handler. The host may search for a handler, install it through its own verified load, and return the new catalog ID. The resolver uses that ID only if the reloaded catalog entry supports the exact convention. available() and handlers() stay installed-only, and if the offer is declined or comes back empty, the original no handler / unsupported * rejection stands.
  • createIntentService() requires resolveSender(windowId), derives the sender from the authenticated endpoint, validates requests, and returns one canonical result.

ok: true means the controller retained responsibility for delivery. It contains archetype, action, convention, and the opaque handler ID. It does not expose a window ID or promise target completion. The controller waits for the current target's authenticated readiness and sends one intent.deliver; host observers receive later completion or failure without a second source result. Source teardown does not cancel accepted work. intent.onDelivery buffers arrivals; INC is not required.

Paja uses verified persistent catalogs separately from live frames. The fixture-line @napplet/[email protected] types predate this contract. The exported intent types (IntentDelivery, IntentRequest, IntentCandidate, and related) are re-exported from @napplet/[email protected], whose delivery has no ID and a required string sender (kehto/web#418).

Quick Start

import {
  createIdentityService,
  createListsService,
  createNotifyService,
  createBleService,
  createDmService,
  createNip17DmAdapter,
  createSerialService,
  createWebrtcService,
} from '@kehto/services';

// Identity service — read-only lookups backed by a signer adapter.
runtime.registerService(
  'identity',
  createIdentityService({
    getSigner: () => signer,
    getProfile: (pk) => nostrClient.fetchProfile(pk),
    getFollows: (pk) => contactListCache.getFollows(pk),
  }),
);

// Notification service — direct NIP-5D notify.* envelopes.
runtime.registerService(
  'notify',
  createNotifyService({
    present: ({ notificationId, message, emit }) => notificationCenter.show({
      notificationId,
      title: message.title,
      body: message.body,
      onClick: () => emit({ type: 'notify.clicked', notificationId }),
    }),
    dismiss: (_windowId, notificationId) => notificationCenter.dismiss(notificationId),
    requestPermission: (_windowId, channel) => notificationPolicy.request(channel),
  }),
);

// Lists service — shell-owned NIP-51 metadata and mutations.
runtime.registerService(
  'lists',
  createListsService({
    supported: () => [{ kind: 10003, type: 'bookmarks', addressable: false }],
    add: (_list, items) => ({ ok: true, added: items.length }),
    remove: (_list, items) => ({ ok: true, removed: items.length }),
  }),
);

// Serial service — runtime-owned serial sessions and host-owned device access.
runtime.registerService(
  'dm',
  createDmService({
    adapter: createNip17DmAdapter({
      ownerSecretKey: shellOwnedSecretKey,
      relayPool: shellRelayPool,
      relays: ['wss://relay.example'],
    }),
  }),
);

runtime.registerService(
  'serial',
  createSerialService({
    open: () => ({ session: { id: 'host-session-1', state: 'open' } }),
    write: (_sessionId, _data) => {},
    close: (_sessionId) => {},
  }),
);

// BLE service — runtime-owned BLE/GATT sessions and host-owned device access.
runtime.registerService(
  'ble',
  createBleService({
    open: () => ({
      session: {
        id: 'host-ble-1',
        state: 'open',
        device: { id: 'host-device-1', name: 'Host BLE' },
      },
    }),
    services: () => [],
    read: () => [87],
    write: (_sessionId, _target, _data) => {},
    subscribe: (sessionId, target, ctx) => {
      ctx.emit({ type: 'notification', sessionId, target, data: [87] });
    },
    unsubscribe: (_sessionId, _target) => {},
    close: (_sessionId) => {},
  }),
);

// WebRTC service — runtime-owned sessions and host-owned signaling/transport.
runtime.registerService(
  'webrtc',
  createWebrtcService({
    open: (request, ctx) => {
      const id = 'host-webrtc-1';
      ctx.emit({ type: 'state', sessionId: id, state: 'open' });
      return {
        session: {
          id,
          scope: request.scope,
          channel: request.channel ?? 'default',
          protocol: request.protocol,
          state: 'open',
        },
      };
    },
    send: (sessionId, payload, ctx) => {
      ctx.emit({ type: 'message', sessionId, from: 'host', payload });
    },
    close: (_sessionId) => {},
  }),
);

When a service is attached to a runtime with Firewall approvals, browser-backed open hooks must call ctx.authorizeDevice(hostPrivateScope, connect) after a chooser returns and before opening the selected port or GATT connection. The scope stays host-private; later serial writes and BLE GATT operations are bound to the source-owned session and require their own operation approval. Revocation closes active device sessions and suppresses late events.

Approval-aware relay services

With runtime operation authorization, OUTBOX getEvent, query, subscribe, and publish require immutable relay planning and execution hooks. Missing hooks fail closed with the correlated result/closed envelope. getEvent uses a planned one-event query; its author hint and relay candidates remain subject to the same approval as other reads. Planned queries receive an optional ApprovalSignal, which the reference router uses to close subscriptions and suppress late results. Standalone OUTBOX routers without runtime authorization retain the legacy API with one FW-OUTBOX-LEGACY-001 warning per service instance.

Relays fail from time to time, so OUTBOX never reports a relay failure as a denial. Following the error codes in NAP-OUTBOX draft #32 at 8865f73:

| Failure | Reason | |---|---| | Relay-list lookup throws or rejects | Falls back to fallbackRelays; a required toInboxes author becomes relay list unavailable | | planRead rejects, or no planned relay attaches | relay list unavailable (or the network reason the router names) | | Planned relays never answer before the deadline | relay timeout, with incomplete: true | | Some planned relays fail, others answer | Events from the rest, with incomplete: true | | No planned relay accepts a publish, or a required own/inbox relay does not accept (even when hinted relays did) | relay timeout | | A plan names an unusable relay URL | Skipped; only a plan with no usable relay, or an unusable required publish relay, is relay list unavailable | | A read plan spans more relay origins than one approval can name | Bounded to the budget (below); a read that left an author without relays is incomplete: true | | A publish's required own/inbox relays span more origins than one approval can name | too many relays, before signing | | The Firewall grant table is full (maxGrants) | approval capacity reached (host capacity, not a denial) | | The approval queue or a rate limit is full, or no prompt UI can answer | approval busy / approval unavailable (not a denial) | | Signer or user declines a publish | publish denied | | Approval denied or cancelled, approval revoked, relay gate refuses every inbox relay, or a router that cannot plan | policy denied |

The draft has no code for "no relay reachable" or "every relay refused", so the closest defined codes are used. Its error list is open ("Common errors include"), and a publish whose required relays cannot fit one approval gets its own non-denial reason, too many relays. A live stream has no incomplete field, so a bounded outbox.subscribe cannot report a lost author (spec gap).

The Firewall caps one request at the host's maxRequirements (default MAX_PERMISSION_REQUIREMENTS, 128; read from ServiceRuntimeContext.maxPermissionRequirements) requirements, which bounds evaluation work, grant growth and prompt size. An OUTBOX plan is not purely host-generated (the napplet picks the authors, third parties publish the relay lists, and read hints are appended), so the plan is bounded to that cap. Each operation contacts at most maxRequirements less one relay origins (127 by default; pass the same budget to the router as maxRelayOrigins), one approval requirement per origin (paths on one origin share it). createRelayPoolOutboxRouter() picks a larger plan's relays by author coverage, deterministically, with napplet hints last. The service also bounds a custom router's plan in the router's order. Publish never drops a required relay; only explicit options.relays extras are trimmed. This follows NAP-OUTBOX Shell Behavior ("The shell MAY use NIP-66 or other relay intelligence to choose among candidate relays") and Security Considerations ("Shells SHOULD enforce limits, timeouts, and maximum subscription counts").

Relay pool and coordinated relay services require publishToRelays to execute a publish plan; a generic publish callback cannot guarantee approved destinations. Hosts must supply the destination-aware callback before publishing through these services.

Theme and identity denials return correlated terminal results. As required by NAP-IDENTITY, denied getPublicKey returns an empty pubkey without an error; other identity reads return their empty result shape with error.

Outbox Streaming Queries

NAP-OUTBOX is still an open upstream draft (napplet/naps PR #32). Its wire outbox.query.result remains one aggregate response. Hosts using Kehto's concrete router can also consume the same bounded read incrementally without changing the napplet wire protocol:

const stream = router.queryStream(
  [{ authors: [author], kinds: [1] }],
  { timeoutMs: 3000 },
  { event: (result) => render(result.event) },
);

const aggregate = await stream.result;

When relay-list loading is asynchronous, the router opens validated relay hints or fallback relays immediately, attaches discovered author write relays to the same deduplicating collector, and applies one deadline to discovery and collection. query() remains the compatibility aggregate over this stream. options.limit applies to that aggregate; the stream receives every verified unique arrival before completion. subscribe() uses the same immediate seed fanout before adding discovered relays.

Keys Service

Reference keyboard / chord backend for the keys.* NIP-5D NAP. By default attaches a single document-level keydown listener that matches incoming events against registered chord subscriptions and delivers a keys.action push envelope back to the owning napplet. Implement the HostKeysBridge interface to swap in OS-level backends (Electron globalShortcut, Tauri GlobalShortcut).

Factory

import { createKeysService } from '@kehto/services';

export function createKeysService(options?: KeysServiceOptions): ServiceHandler & { destroy(): void };

destroy() detaches the document listener (or the bridge's unsubscribe handles) and clears all subscription registries. Call on shell teardown.

KeysServiceOptions

| Field | Type | Description | |-------|------|-------------| | onForward | (event: { key, code, ctrlKey, altKey, shiftKey, metaKey }) => void | Called on keys.forward envelopes and on document/host-bridge keydowns handled by the reference backend. DOM-shape payload (the service translates from the wire-format { ctrl, alt, shift, meta } before invoking this callback). Forwarded keys do not dispatch keys.action; active napplets suppress bound keys locally from keys.bindings before forwarding. | | listenerTarget | EventTarget | Defaults to document. Pass a fresh new EventTarget() in unit tests to isolate the listener. Ignored when hostBridge is provided. | | hostBridge | HostKeysBridge | Pluggable OS-bridge. When provided, the service delegates keys.registerAction to bridge.subscribe(chord, cb) and the default document listener is NOT attached. | | reservedChords | ReadonlyArray<string> | Optional set of shell-reserved chords (wire-format strings like 'Ctrl+Shift+K', 'Cmd+P'). Reserved chords are not assigned as napplet action bindings. Document keydowns that match a reserved chord call onForward but do not dispatch keys.action. Precedence: reserved > registered. Normalized once at construction via the same parser used for action.defaultKey. See Reserved Chords. |

HostKeysBridge interface

Copy the contract verbatim for host-app implementers. OS-level bridges implement subscribe at minimum; the two optional fields enable global-hotkey registration (works even when the host window is unfocused).

export interface HostKeysBridge {
  /**
   * Subscribe a callback to a chord. Returns an unsubscribe handle.
   *
   * Implementations MUST:
   *   - invoke `callback` exactly once per matching chord event (implementations
   *     are responsible for any OS-autorepeat filtering)
   *   - invoke `callback` synchronously during the event delivery
   *   - remove only this subscription when its unsubscribe handle is called;
   *     other callbacks for the same chord must remain live
   *   - accept the string chord format documented by @napplet/nap/keys
   *     (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`)
   */
  subscribe(chord: string, callback: (event: KeyboardEvent | HostKeyEvent) => void): () => void;

  /**
   * Optional: register an OS-level global hotkey (works even when the host
   * window is not focused). Returns true on success, false if the chord
   * cannot be registered (e.g. already claimed by another app).
   *
   * Omitted by the browser reference implementation — browsers cannot
   * register OS-level global hotkeys without privileged APIs. Electron
   * (`globalShortcut`) and Tauri (`GlobalShortcut`) provide this.
   */
  registerGlobalHotkey?(chord: string): boolean;

  /**
   * Optional: subscribe to OS-level global hotkey events (regardless of
   * focus). Returns an unsubscribe handle.
   *
   * Omitted by the browser reference implementation. See
   * {@link HostKeysBridge.registerGlobalHotkey}.
   */
  onGlobalHotkey?(callback: (chord: string) => void): () => void;
}

Usage

Default browser path — the reference document-level chord listener:

import { createKeysService } from '@kehto/services';

const keys = createKeysService({
  onForward: (event) => {
    // DOM-shape payload: { key, code, ctrlKey, altKey, shiftKey, metaKey }
    hotkeyDispatcher.dispatch(event);
  },
});

runtime.registerService('keys', keys);
// On shell teardown:
keys.destroy();

Custom bridge path — swap in Electron's globalShortcut:

import { createKeysService, type HostKeysBridge, type HostKeyEvent } from '@kehto/services';
import { globalShortcut } from 'electron';

const subscribers = new Map<string, Set<(event: HostKeyEvent) => void>>();
const electronBridge: HostKeysBridge = {
  subscribe(chord, cb) {
    let callbacks = subscribers.get(chord);
    if (!callbacks) {
      const group = new Set<(event: HostKeyEvent) => void>();
      const registered = globalShortcut.register(chord, () => {
        for (const callback of group) callback({
          key: '', code: '',
          ctrlKey: false, altKey: false, shiftKey: false, metaKey: false,
        });
      });
      if (!registered) throw new Error(`Cannot register ${chord}`);
      callbacks = group;
      subscribers.set(chord, callbacks);
    }
    callbacks.add(cb);
    return () => {
      if (!callbacks.delete(cb)) return;
      if (callbacks.size === 0) {
        globalShortcut.unregister(chord);
        subscribers.delete(chord);
      }
    };
  },
};

runtime.registerService('keys', createKeysService({ hostBridge: electronBridge }));

When to plug a custom bridge

Plug a HostKeysBridge when the default document listener is insufficient: Electron or Tauri apps that need to register OS-level global hotkeys (chords delivered even when the host window is not focused), native shells that route chords through a platform-specific hotkey manager (macOS Carbon, Linux X11 grab, Windows RegisterHotKey), or test harnesses that inject synthetic events through a controlled EventTarget. The bridge owns subscription lifecycle; the service retains per-window bookkeeping (so onWindowDestroyed cleanup stays identical across paths).

A napplet drives this end to end via @napplet/sdk — keys.registerAction to claim a chord and keys.onAction to receive dispatches against the real backend. After a successful bound registration, the service pushes a complete keys.bindings list for that napplet/window, using entries shaped as { actionId, key }. It pushes the complete list again after keys.unregisterAction removes a binding, including an empty list when no bindings remain. Injected shims use that list to suppress locally-bound keydowns before forwarding.

Action IDs are local to the trusted window passed by the runtime. Two windows may each register game.a, including with the same suggested key, without replacing one another's bindings. Unregistering or destroying one window removes only its actions and bridge subscriptions. Binding lists and keys.action messages retain the original app-local action ID; callers do not need to invent window-specific IDs. Re-registering an action in the same window retains the existing rebind behavior: a valid available chord replaces that window's binding, a reserved chord removes its previous binding, and a malformed chord or failed bridge subscription leaves the previous binding intact.

This ownership scope is an explicit Kehto policy for the scope left implicit by NAP-KEYS PR #9 at cecb642. The draft describes duplicate-action errors but does not mandate service-global IDs or forbid same-owner updates. Window-scoped ownership preserves its per-napplet binding delivery and adds no wire fields. Chord conflicts retain the existing behavior: matching registered actions receive their own keys.action push.

Reserved Chords

Shell-reserved chords let a host application (window manager, launcher shell, tiling WM) claim specific chords for its own dispatch regardless of what napplets subscribe to. Declare the reserved set once at service construction via the reservedChords option on KeysServiceOptions:

import { createKeysService } from '@kehto/services';

const keys = createKeysService({
  reservedChords: [
    'Ctrl+Alt+T',        // launcher
    'Super+Space',       // workspace switch
    'Ctrl+Shift+Y',      // shell palette
  ],
  onForward: (event) => {
    // The shell's WM dispatcher — fires for reserved chords regardless of
    // which napplet (if any) tried to register them.
    wmLauncher.dispatch(event);
  },
});

runtime.registerService('keys', keys);

One result per request. Every keys.registerAction gets exactly one keys.registerAction.result while its window is live, as NAP-KEYS (napplet/naps#9 at 8869a4cf) requires. When the approval doesn't execute, the result carries error and echoes actionId (or ''): denied and cancelled send policy denied, while capacity, busy and unavailable send approval capacity reached, approval busy and approval unavailable. Those are host conditions, not denials. NAP-KEYS names no code for them, so the strings are a recorded spec gap. A source whose permission is revoked mid-approval still gets its policy denied result; only a destroyed window gets no reply.

Precedence contract: reserved > binding. When a napplet registers an action whose defaultKey matches reservedChords, the service acknowledges the action with keys.registerAction.result but leaves binding undefined and does not add the chord to keys.bindings. That prevents the active napplet from suppressing a shell-owned chord locally.

  • If a document keydown matches a reserved chord: onForward fires exactly once and no keys.action envelope is dispatched.
  • If a document keydown matches a non-reserved registered binding: onForward fires and every napplet whose registered action matches receives a keys.action envelope via its captured send handle.
  • If a napplet sends keys.forward: onForward fires and the service does not dispatch keys.action. Active napplets are expected to suppress bound keys locally from keys.bindings before forwarding.

Reserved chords are normalized at service construction via the same parser used for action.defaultKey, so 'Ctrl+Shift+K', 'Control+shift+k', and 'ctrl+Shift+K' all match the same chord. Modifier aliases (Cmd / Command / Win / Super → meta; Control → ctrl; Option → alt) are recognized case-insensitively.

WM-launcher integration example:

// Shell-side: declare every WM-absolute chord at boot.
const keys = createKeysService({
  reservedChords: Object.keys(wmChordMap),    // e.g. ['Super+1', 'Super+2', ..., 'Ctrl+Alt+T']
  onForward: (event) => {
    const chordStr = chordStringFromEvent(event);
    const action = wmChordMap[chordStr];
    if (action) action.execute();
  },
});
runtime.registerService('keys', keys);

// Napplet-side (hotkey-chord napplet, for example): free to request
// `Ctrl+Shift+K` via keys.registerAction. If Ctrl+Shift+K is NOT in the shell's
// reservedChords, the napplet receives a binding and can handle it locally while
// active. If the shell reserves that chord, the registration result is unbound
// and no suppress-list entry is pushed.

Dynamic reservation is out of scope for v1.6. If a downstream shell needs runtime updates to the reserved set (e.g. "reservation depends on which workspace is active"), open an issue referencing HostKeysBridge.reserveAbsolute(chords) — the deferred extension shape. Until then, reservedChords is static at service construction.

OS-level global hotkeys remain a separate concern. reservedChords operates at the service layer. For OS-level reservation (chord fires even when the host window is unfocused), implement HostKeysBridge.registerGlobalHotkey in your bridge — reserved chords and global hotkeys compose orthogonally.

Media Service

Reference media backend for the media.* NIP-5D NAP. By default mirrors session metadata + playback state to navigator.mediaSession via the DOM MediaSession API and installs setActionHandler callbacks that emit media.command push envelopes on OS transport events (play / pause / next / previous / seek). Implement the HostMediaBridge interface to swap in native backends (Electron bridge, MPRIS on Linux, MediaRemote on macOS).

Factory

import { createMediaService } from '@kehto/services';

export function createMediaService(options?: MediaServiceOptions): MediaService;

destroy() tears down the active bridge (removes setActionHandler listeners, removes the silent-audio prime element in the browser reference implementation) and clears the session registry.

See Media playback for the browser audio/video backend, player mounting, draft conformance authority, supported source formats, lifecycle, and migration from legacy command callbacks. Paja uses this player.

MediaServiceOptions

| Field | Type | Description | |-------|------|-------------| | playback | MediaPlaybackBackend | Source-policy and actual output backend; use createBrowserMediaPlayback({ resource }). | | maxSessionsPerWindow | number | Active plus pending session limit (default 16). | | onSessionCreate | (windowId, sessionId, metadata?) => void | Called when a napplet creates a session. | | onState | (windowId, sessionId, state) => void | Called on media.state updates — high-frequency; keep handler work minimal. | | onSessionDestroy | (windowId, sessionId) => void | Called when a napplet destroys a session. | | onSessionUpdate | (windowId, sessionId, metadata) => void | Called when a napplet updates session metadata. | | onCapabilities | (windowId, sessionId, actions) => void | Called when a napplet declares capabilities for a session. | | mediaSessionTarget | MediaSessionTarget | Overrides navigator.mediaSession (used by the default bridge only). Pass a MockMediaSession in unit tests. Ignored when hostBridge is provided. | | documentTarget | Document \| null | Overrides document (used by the default bridge only). Set to null to disable the silent-audio prime in unit tests. Ignored when hostBridge is provided. | | hostBridge | HostMediaBridge | Pluggable backend. When provided, the service delegates setMetadata / setPlaybackState / onAction to the bridge and skips navigator.mediaSession entirely. |

HostMediaBridge interface

Copy the contract verbatim for host-app implementers. Native bridges implement setMetadata + setPlaybackState + onAction at minimum; the two optional fields cover active-session switching and per-session teardown.

export interface HostMediaBridge {
  /**
   * Set the metadata displayed on the OS transport surface for a session.
   * Called on session.create (with initial metadata) and on session.update
   * (with merged metadata) whenever the session is the active session.
   * Implementations MUST be idempotent.
   */
  setMetadata(sessionId: string, metadata: MediaMetadata): void;

  /**
   * Set the playback state for a session. Called on media.state reports
   * whenever the session is the active session. State strings match
   * nap-media MediaState.status exactly. Implementations MUST be idempotent.
   */
  setPlaybackState(sessionId: string, state: 'playing' | 'paused' | 'stopped' | 'buffering'): void;

  /**
   * Subscribe to OS-level action events (user clicks play/pause/seek/next/prev
   * on the transport surface). Returns an unsubscribe handle.
   *
   * The callback receives `(sessionId, action, value?)`. `sessionId` is the
   * bridge's currently-active session (the browser impl tracks this internally
   * via setActionHandler-at-fire-time; native impls track via setActiveSession).
   * `value` is populated for `action === 'seek'` (seek target in seconds) and
   * for `action === 'volume'` (0.0-1.0). The service dispatches the resulting
   * `media.command` envelope to the owning napplet of that session.
   */
  onAction(callback: (sessionId: string, action: MediaAction, value?: number) => void): () => void;

  /**
   * Optional: notify the bridge that the active session has changed. The
   * browser reference impl uses this to switch which session's metadata/state
   * is mirrored to the singleton navigator.mediaSession and to install (or
   * clear) action handlers for the session's declared capabilities.
   *
   * The optional `actions` parameter carries the session's declared capability
   * set so the bridge can narrow which OS transport buttons are active. When
   * omitted, the bridge applies its default set. Native OS bridges that track
   * active-session state internally may omit this field entirely.
   */
  setActiveSession?(sessionId: string | null, actions?: readonly MediaAction[]): void;

  /**
   * Optional: tear down per-session resources. The browser reference impl
   * uses this to remove the silent-audio prime element when the last session
   * is destroyed. Bridges that need no per-session teardown may omit this field.
   */
  destroySession?(sessionId: string): void;
}

Usage

Default browser path — the reference navigator.mediaSession mirror:

import { createMediaService } from '@kehto/services';

const media = createMediaService({
  onSessionCreate: (windowId, sessionId, metadata) => {
    console.log(`[${windowId}] created session ${sessionId}`, metadata);
  },
  onState: (windowId, sessionId, state) => {
    nowPlaying.update(windowId, state);
  },
});

runtime.registerService('media', media);
// On shell teardown:
media.destroy();

Custom bridge path — swap in an Electron host bridge:

import { createMediaService, type HostMediaBridge, type MediaAction } from '@kehto/services';
import { mediaBridge } from './electron-media-bridge';

const electronBridge: HostMediaBridge = {
  setMetadata(sessionId, md) {
    mediaBridge.sendMetadata({ sessionId, md });
  },
  setPlaybackState(sessionId, state) {
    mediaBridge.sendPlaybackState({ sessionId, state });
  },
  onAction(cb) {
    const handler = (_: unknown, msg: { sessionId: string; action: MediaAction; value?: number }) =>
      cb(msg.sessionId, msg.action, msg.value);
    mediaBridge.onAction(handler);
    return () => mediaBridge.offAction(handler);
  },
};

runtime.registerService('media', createMediaService({ hostBridge: electronBridge }));

When to plug a custom bridge

Plug a HostMediaBridge when navigator.mediaSession is insufficient: Electron apps that need to route transport events through the main process (lock-screen integration on Windows, Now Playing integration on macOS), Linux shells that speak MPRIS over D-Bus, native mobile wrappers that forward to AVPlayer / ExoPlayer, or test harnesses that record action events without touching the DOM. The bridge owns metadata/state mirroring and OS action routing; the service retains per-session bookkeeping (sessionRegistry + per-window send handles) so media.command dispatch semantics stay identical across paths.

A napplet drives this end to end via @napplet/nap/media — mediaCreateSession({ owner: 'napplet', ... }), mediaReportState, and mediaOnCommand against the real backend.

Public API

Each factory returns a ServiceHandler registrable via runtime.registerService(). The bullets below note the current NIP-5D domain the handler owns and the ACL capability napplets need in order to reach it.

Identity NAP

  • createIdentityService — identity.* reads (identity:read). No signing surface; shell mediates signing internally.

createIdentityService uses getSigner() for identity.getPublicKey and identity.getRelays. Hosts may also pass optional read-only provider hooks for getProfile, getFollows, getList, getZaps, getMutes, getBlocked, and getBadges. These hooks receive the current signer pubkey (or "" when no signer is connected) and return the payload portion of the corresponding .result envelope. Kehto does not query relays itself; the hooks are for hosts that already maintain profile, contact-list, list, zap, moderation, or badge data.

Notify NAP

  • createNotifyService — canonical direct notify.* envelopes per NAP-NOTIFY PR #11 at 67877ef6. Runtime approval scopes presentation, permission requests, badges, and channels to the exact operation/channel. Payloads are copied before approval; revoked or destroyed sources cannot render or receive late callbacks. Remote icon URLs are rejected until a host supplies an approved NAP-RESOURCE fetch. notify.dismiss silently ignores unknown or foreign IDs and stays available after revocation. Paja also checks the current verified artifact before caching a browser notification permission.
  • createNotificationService — deprecated Kehto notify.create/list/read registry with a once-per-instance FW-NOTIFICATION-LEGACY-001 diagnostic. No upstream NAP defines this wire; new consumers should use notify.send.

Relay NAP

  • createRelayPoolService — relay.publish, relay.publishEncrypted, relay.subscribe fan-out (relay:read / relay:write). Publish handlers receive only runtime-signed events and settle with canonical { ok, event, eventId } or { ok: false, error } result envelopes. Subscribe adapters may pass observed relay URLs as the callback's second argument so RelayEventResult.sidecar.relayHints records provenance rather than the larger requested relay set.
  • createCacheService — offline event cache (cache:read / cache:write).
  • createCoordinatedRelay — composite service that bundles relay-pool + cache with read-through behavior and the same canonical publish result.

Keys NAP

  • createKeysService — keys.registerAction / keys.unregisterAction / keys.forward + keys.bindings / keys.action push envelopes (keys:forward). Document-level chord listener by default; implement the HostKeysBridge interface to swap in Electron / Tauri / OS-level backends. See Keys Service for the full contract.

Media NAP

  • createMediaService — owner-aware media.session.create / update / destroy / media.state / media.capabilities + media.command push envelopes (media:control). Napplet-owned sessions mirror to navigator.mediaSession by default; shell-owned playback uses the optional MediaPlaybackBackend, with createBrowserMediaPlayback and mountMediaPlayer providing the browser implementation. Implement the HostMediaBridge interface to swap in native backends. See Media Service for the full contract.

BLE NAP

  • createBleService — ble.open, ble.services, ble.read, ble.write, ble.subscribe, ble.unsubscribe, ble.close + host-pushed ble.event envelopes. Hook contexts include ctx.emit(event), so host Bluetooth notification listeners can forward notification, state, and closed events to the requesting napplet without replacing the reference handler. Under runtime approvals, ctx.authorizeDevice(...) binds a host-private selected device before connection; each GATT operation is separately authorized and source-owned.

WebRTC NAP

  • createWebrtcService — webrtc.open, webrtc.send, webrtc.close + host-pushed webrtc.event envelopes. The reference handler owns only the NAP request/result bookkeeping; host bridges own signaling, SDP, ICE, peer connection lifecycle, and policy. ctx.emit drops events for a sessionId the window does not own; webrtc.close takes the session out of delivery before the host close hook runs, so nothing for it reaches the napplet afterwards. A session the backend ends is forgotten once its closed event is delivered, so later events are dropped and later webrtc.send/webrtc.close get session not found. A napplet-initiated close gets no closed event. Policy revocation (onPermissionRevoked, or an ACL block) sends closed with reason policy denied for each live session, then forgets it; requests already in flight still get their result. Window destroy stays silent.

DM NAP

  • createDmService — dm.status, dm.conversations, dm.messages, dm.send, dm.subscribe, dm.unsubscribe + dm.message push envelopes (dm:read / dm:write). Runtime owns correlation, subscriptions, cleanup, and normalized message shape; adapters own protocol transport.
  • createNip17DmAdapter — concrete NIP-17 gift-wrap adapter backed by nostr-tools/nip17 and an injected relay pool. The owner secret key stays shell/runtime-owned.
  • createNdrDmAdapter / createNdrRelayTransport — structural adapter for Nostr Double Ratchet runtimes plus a relay transport bridge for app-owned nostrSubscribe / nostrFetch / nostrPublish hooks.
  • createCordnDmAdapter / createCordnRelayCoordinatorClient — structural adapter for Cordn/ContextVM clients plus a relay-backed coordinator bridge for PostGroupMessage, FetchGroupMessages, and SubscribeGroupMessages.

FS NAP

  • createFsService — all fs.* request/result envelopes plus scoped fs.changed pushes. It guarantees same-id results, error/success-field exclusivity, cross-window watch isolation, and window-destroy cleanup.
  • FsBackend — host contract for runtime-owned virtual paths, real picker/storage handles, bounded range I/O, atomic writes, directory mutation, and advisory watches. FsServiceError maps failures to the closed NAP-FS error set.

Theme NAP

  • createThemeService — theme.get plus automatic theme.changed delivery (theme:read). Returns a ThemeService with publishTheme() and getCurrentTheme() for host-side updates.

Intent NAP

  • createIntentService — exact intent.invoke, intent.available, and intent.handlers request/result handling plus recipient-gated intent.changed. Failures keep the required availability (empty, available: false) or handlers: [] beside error, as the NAP-INTENT wire table lists them.
  • manifestToIntentCatalogEntry — verified manifest archetype contracts to catalog entries.
  • createCatalogIntentResolver — exact convention selection and retained target-controller seam.

Identity and theme wire guarantees

Against NAP-IDENTITY/NAP-THEME at napplet/naps master 5ac0490461ca6fec2f0d2e45b4835cf9bc08de24, createIdentityService is readonly: identity.getPublicKey always sends one matching .result with pubkey: "" when a signer is absent or fails, and the other supported reads retain their safe primary result fields. Unknown identity actions are silent; identity changed values are host pushes, not request retries or INC/intent traffic.

createThemeService accepts theme.get only and owns the current complete three-color theme. publishTheme() normalizes and stores that state before it invokes its one bridge callback, so an immediate theme.get observes the same value as the automatic push. There is no theme subscribe/unsubscribe protocol. For denied or unavailable runtime reads, Kehto uses the fixed non-sensitive complete normal result without error: this explicit policy reconciles the draft error-only example without a mixed theme/error extension.

Types

AudioSource, AudioServiceOptions, Notification, NotificationServiceOptions, IdentityServiceOptions, RelayPoolServiceOptions, CacheServiceOptions, CoordinatedRelayOptions, KeysServiceOptions, MediaServiceOptions, NotifyServiceOptions, NotifyPresentation, NotifyInteractionMessage, ThemeServiceOptions, ThemeService, IntentRequest, IntentResult, IntentCandidate, IntentAvailability, IntentResolver, IntentTargetController, IntentDispatchParams, IntentTargetDispatch, BleServiceOptions, BleServiceContext, WebrtcServiceOptions, WebrtcServiceContext, DmServiceOptions, DmAdapter, DmRelayPool, Nip17DmAdapterOptions, NdrDmAdapterOptions, CordnDmAdapterOptions.

API Reference

Full package docs: docs/packages/services.md. Generated API module: docs/api/modules/_kehto_services.html (run pnpm docs:api).

License

MIT

NIP-5D event compatibility

Current manifests use a direct artifact x hash, plain-text content, role-matched z/i intent declarations, and required R / optional O domains. Kehto also accepts legacy aggregate events through an isolated compatibility adapter. Existing aggregateHash host/cache/ACL fields carry the verified artifact hash for current events; legacy identities keep their original aggregate. Both paths verify signatures and bytes before runtime injection and srcdoc execution. For the schema and removal boundary, see event migration.

Canonical intent contracts

@kehto/services temporarily owns the canonical NAP-INTENT PR #106 contracts. @napplet/[email protected] (the fixture line) has not published them; @napplet/[email protected] now exports IntentCandidate and related types and @napplet/[email protected] declares intent.onDelivery, so adopting the upstream types and removing the local mirror is a tracked follow-up, not part of the NAP-LLM change. Candidates use opaque id plus exact contracts; successful results contain only ok, archetype, action, convention, and handler (never handled, windowId, or newWindow). createIntentService requires resolveSender(windowId) and rejects caller-supplied sender fields. IntentResolverContext.sourceWindowId and IntentDispatchParams.sourceWindowId are host-only correlation fields: they must never appear in intent.deliver or intent.invoke.result. A target controller accepts retained work as { completion }; completion failure is host observation, not a second canonical result. Remove these local types only when an upstream package exports the checked PR #106 surface and Kehto's service/runtime regression suite proves direct replacement.

GAMEPAD integration

This non-normative guidance defers to NAP-GAMEPAD at napplet/naps@19de5ce1. Services export createGamepadService and browserGamepadOptions; shell exports denyNappletControllerAccess. Paja registers one host reader and denies native gamepad/HID/USB paths before frame execution. A runtime-approved gamepad.subscribe must authorize the host-private gamepad:input resource before the reader starts; the NAP has no device handle for a narrower scope. Denial emits reason: "blocked". Only the visible host's input owner receives live controls; focus loss supplies neutral controls and timestamp zero. Unsubscribe, revocation, window destruction, and service removal release polling. 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.

Resource request lifecycle

Resource requests are tracked before asynchronous metadata resolution. Cancelling byte requests before that resolution prevents a fetch; cancelling an active fetch aborts its signal and suppresses its terminal response. Window destruction and service detachment cancel outstanding work, including advisory info responses. The service captures each exact url or ordered urls list before awaiting host work. A duplicate in-flight ID cannot replace the original cancellation handle, and old source cleanup cannot remove a replacement source's request. Successful results carry canonical padded RFC 4648 base64 in blob; shell consumers decode only that canonical form into a Blob. resource.cancel stays silent, while a live permission revocation emits exactly one blocked-by-policy terminal and suppresses stale completions.

These lifecycle rules were checked against NAP-RESOURCE PR #80 at ae5b9c64ab8a4d8909f288829a01e99d6bd713bc. The NAP package declarations are behind that draft, so Kehto keeps its local envelope types only until packaged exports catch up.

Scoped resource authorization

When attached to a runtime configured with permissions, the resource service checks each original URL against a resource grant and, for HTTP(S) or WebSocket destinations, a separate origin grant. Interface permission remains required. Bulk requests authorize each item independently. The authorization covers fetching and reading the response body, so revocation can abort active work and discard late bytes. Request cancellation also dismisses a pending approval without granting a late answer.

Resolvers must call init.authorizeNetwork(destination, execute) before every actual HTTP(S) or WebSocket contact. That callback runs under a distinct origin requirement, including each proxy-reported redirect hop, and its signal covers connection and body reading. Paja's local proxy adds DNS-time address screening and pinned connections; see Paja resource proxy policy.

This host-side boundary does not isolate unrestricted iframe subresource or direct network access. Phase 114 must close frame admission/CSP isolation before any end-to-end resource-security claim is made.

Standalone or unmigrated hosts retain resolver-owned policy with diagnostic FW-RESOURCE-LEGACY-001, once per service instance on actual fetch use. Configure RuntimeAdapter.permissions and trusted session permissionPrincipal to use shared grants. No old origin list is imported into Firewall permission grants.

Resource request replay policy

Kehto retains the latest 1,024 completed resource request IDs per source window. Reusing a retained ID, including with a different resource operation or malformed payload, causes no additional resolver call or terminal response. Active IDs are tracked separately and cannot be evicted by completed requests. Cancellation always reaches active work; cancelled IDs enter the replay ledger when their work settles. Source destruction and service detachment clear the corresponding history. This bounded Kehto policy supplements NAP-RESOURCE's cancellation rules; callers should generate fresh IDs because older completed entries are evicted.

WebRTC plans declare every configured ICE endpoint before approval. The reference handler requests typed network/ice scopes; it invokes no peer hook on denial. Synchronous send failures return the matching result ID. Byte payloads (NAP-WEBRTC #59 fb4dd6f0) need a sendBytes(sessionId, bytes, context) hook, which receives the decoded Uint8Array and must send it as one binary payload, never as base64 text. Before the hook runs, the service rejects non-canonical padded base64 with invalid request and anything over the session's reported maxPayloadBytes with payload too large. The limit counts decoded bytes for sendBytes and serialized JSON bytes for send, and it applies only when the open result reports maxPayloadBytes. A host emits peer bytes as { type: 'bytes', sessionId, from, bytes } with encodeWebrtcBytes; the service drops a bytes event whose text is not canonical. Without the hook, webrtc.sendBytes answers unsupported, as NAP-WEBRTC requires of a shell without byte payloads. encodeWebrtcBytes / decodeWebrtcBytes are exported for hosts. A stats request gets no reply, since NAP-WEBRTC defines stats only as a pushed event.

Every reference service drops a message whose type its NAP does not define, without a reply (NIP-5D), and warns the host once per domain/type through createUnrecognizedTypeDiagnostic from @kehto/runtime.