@kehto/runtime 0.24.1 → 0.25.1

package/README.md

@@ -40,6 +40,20 @@ The runtime is built around the current draft dispatch contract from `@napplet/c
 
 Signing is shell-mediated inside `relay.publish` / `relay.publishEncrypted` (NIP-44 default, NIP-04 opt-in). The legacy signer domain is dissolved — napplets never see a host-injected nostr object and cannot call signer-sign RPCs directly.
 
+### NAP-RELAY subscription revocation
+
+Revoking `relay:read` or blocking a principal immediately retires ordinary relay
+subscriptions in every window with that exact `dTag` and aggregate hash. The
+runtime closes registered relay/cache backends and direct adapter subscriptions,
+sends `relay.closed` with reason `denied: relay:read`, and suppresses queued events
+and EOSE callbacks. Regranting access requires a new subscription; old callbacks
+remain invalid even if the same `subId` is reused. Other principals, other artifact
+versions, and revocation of unrelated capabilities leave subscriptions active.
+
+This host policy conforms to [NAP-RELAY draft PR #2 at
+`9f30b3505335a52c574ff570576687d6467021ff`](https://github.com/napplet/naps/blob/9f30b3505335a52c574ff570576687d6467021ff/naps/NAP-RELAY.md),
+which permits ACL enforcement and policy-driven subscription termination.
+
 ### NAP-RELAY publish boundary
 
 The publish path follows draft [NAP-RELAY PR #2 at
@@ -223,10 +237,24 @@ implementations of `FirewallStateContainer` must provide this method.
 - `cleanupNappState` — remove persisted state when a napplet window closes
 
 ### Service dispatch
-- `routeServiceMessage` — domain-prefix router into the service registry
+- `routeServiceMessage` — policy-free domain selection primitive; never a fallback for untrusted ingress
 - `notifyServiceWindowDestroyed` — lifecycle fan-out to every service handler
 - Service-only NAP domains, including `dm` and `fs`, route through handlers registered with `runtime.registerService('<domain>', handler)`.
 
+For domains outside the built-in dispatcher, handlers opt in with an exact
+`messageCapabilities` map (existing ACL capability or explicit `null` per inbound
+type). `Runtime.handleMessage` requires a live unblocked source, an explicit
+`isDomainAllowed` grant, the declared ACL grant, and firewall admission. Unknown
+types and extension policy denials stay silent on the wire. Registration alone
+attaches a service; it does not expose or grant a domain. Fixed NAP routes retain
+their own authorization. Pending replies are invalidated by service/source
+replacement or teardown and recheck current domain/ACL policy.
+
+Browser hosts must provide the owning extension contract and inject its granted
+namespace binding before scripts run. Stock Paja/playground bindings do not inject
+arbitrary extensions. See [Register a service](../../docs/how-tos/register-service.md#domains-outside-the-built-in-dispatcher)
+for the complete host contract and spec bounds.
+
 ### Types
 40+ interfaces — including `Runtime`, `RuntimeAdapter`, `SendToNapplet`, `RelayPoolAdapter`, `ServiceHandler`, `ServiceRegistry`, `NappletMessage`, `SessionEntry`, `AclEntryExternal`, `AclCheckEvent`, and the per-adapter hook types — are exported from `./types.js` for host-app integration.
 

package/dist/index.d.ts

@@ -583,12 +583,12 @@ interface ServiceRuntimeContext {
  *
  * @example
  * ```ts
- * const audioHandler: ServiceHandler = {
- *   descriptor: { name: 'audio', version: '1.0.0' },
- *   handleMessage(windowId, message, send) {
- *     if (message.type === 'inc.emit') {
- *       // process audio inc event...
- *       send({ type: 'inc.emit.result', id: (message as any).id });
+ * const exampleHandler: ServiceHandler = {
+ *   descriptor: { name: 'example', version: '1.0.0' },
+ *   messageCapabilities: { 'example.ping': null },
+ *   handleMessage(_windowId, message, send) {
+ *     if (message.type === 'example.ping') {
+ *       send({ type: 'example.pong' });
  *     }
  *   },
  * };
@@ -597,6 +597,19 @@ interface ServiceRuntimeContext {
 interface ServiceHandler {
     /** Metadata describing this service. */
     descriptor: ServiceDescriptor;
+    /**
+     * Explicit inbound types for a domain outside the built-in dispatcher.
+     * Each own key is an exact `domain.action` type; its value is an existing
+     * ACL capability or explicit `null` for no additional capability requirement.
+     * Omission keeps non-built-in services attachment-only. Built-in NAP routes
+     * ignore this map and retain their canonical capability mapping.
+     *
+     * Extension dispatch also requires a live, unblocked source, an explicit
+     * `RuntimeAdapter.isDomainAllowed` grant, and firewall admission. This map
+     * neither injects a namespace binding nor grants any capability. The handler
+     * owns payload validation and its extension's response contract.
+     */
+    messageCapabilities?: Readonly<Record<string, Capability | null>>;
     /**
      * Attach this handler to one runtime instance.
      *
@@ -623,14 +636,14 @@ interface ServiceHandler {
 }
 /**
  * Registry of services available to napplets.
- * Each key is a service name (e.g., 'audio', 'notifications').
- * Napplets discover available services via kind 29010 service discovery events.
+ * Keys select exact wire domains for direct routing (e.g., 'notify').
+ * Metadata/attachment alone does not expose a domain. Custom domains require
+ * ServiceHandler.messageCapabilities and explicit host domain authorization.
  *
  * @example
  * ```ts
  * const services: ServiceRegistry = {
- *   audio: audioHandler,
- *   notifications: notificationHandler,
+ *   notify: notificationHandler,
  * };
  * ```
  */
@@ -692,8 +705,9 @@ interface RuntimeAdapter {
     sendToNapplet: SendToNapplet;
     /**
      * Determines whether a session-established napplet may invoke a NAP domain.
-     * When omitted, every domain remains eligible for dispatch. Browser shells
-     * use this to enforce the immutable environment delivered in `shell.init`.
+     * 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.
      */
     isDomainAllowed?: (windowId: string, domain: string) => boolean;
     /**
@@ -792,14 +806,17 @@ interface RuntimeAdapter {
     /**
      * Optional service extensions. Shell/host registers service handlers here
      * for static initialization. Services can also be added dynamically via
-     * runtime.registerService(). Each key is a service name (e.g., 'audio').
+     * runtime.registerService(). 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.
      *
      * @example
      * ```ts
      * const hooks: RuntimeAdapter = {
      *   // ... required adapters ...
      *   services: {
-     *     audio: myAudioServiceHandler,
+     *     notify: myNotificationServiceHandler,
      *   },
      * };
      * ```
@@ -1456,7 +1473,11 @@ interface Runtime {
      * Register a service handler dynamically after runtime creation.
      * If a handler is already registered for this name, it is replaced.
      *
-     * @param name - Service name (e.g., 'audio', 'notifications')
+     * Built-in domains keep their NAP routing. Other domains require the
+     * handler's exact messageCapabilities map and an explicit host domain grant.
+     * Registration never injects namespace bindings or grants capabilities.
+     *
+     * @param name - Exact domain name (e.g., 'notify' or a host extension)
      * @param handler - The service handler implementation
      */
     registerService(name: string, handler: ServiceHandler): void;
@@ -1580,9 +1601,12 @@ declare function cleanupNappState(pubkey: string, dTag: string, aggregateHash: s
  * Route a NappletMessage envelope to the matching service handler.
  *
  * Direct NAP-domain services are routed by the domain in their wire
- * message.type (e.g., 'signer.signEvent' -> 'signer' service). INC messages
+ * message.type (e.g., 'notify.send' -> 'notify' service). INC messages
  * are owned by the INC runtime; their topic values are opaque here.
  *
+ * This low-level selection primitive performs no source, domain, ACL,
+ * messageCapabilities, or firewall checks. Never call it as a fallback for
+ * untrusted input; host ingress must use Runtime.handleMessage.
  * Returns true if a service handled the message, false otherwise.
  *
  * @param windowId - The napplet window that sent the message

package/dist/index.js

@@ -565,11 +565,52 @@ function relayEventResultFromCarrier(carrier) {
 // src/runtime.ts
 import { createDispatch } from "@napplet/core";
 
+// src/service-extensions.ts
+import { ALL_CAPABILITIES } from "@kehto/acl/capabilities";
+function createServiceExtensionRouter(context) {
+  const { hooks, services, registrations, sessions, acl, enforce, firewall } = context;
+  const windowLifetimes = /* @__PURE__ */ new Map();
+  function handleMessage(windowId, message) {
+    const dot = message.type.indexOf(".");
+    const domain = message.type.slice(0, dot);
+    if (dot <= 0 || dot === message.type.length - 1 || !/^[a-z][a-z0-9-]*$/.test(domain) || !Object.hasOwn(services, domain)) return;
+    const handler = services[domain];
+    const policies = handler.messageCapabilities;
+    if (!policies || !Object.hasOwn(policies, message.type)) return;
+    const capability = policies[message.type];
+    if (capability !== null && !ALL_CAPABILITIES.includes(capability)) return;
+    const session = sessions.getEntryByWindowId(windowId);
+    const registration = registrations.get(domain);
+    if (!session || !registration) return;
+    const allowed = () => hooks.isDomainAllowed?.(windowId, domain) === true && !acl.isBlocked("", session.dTag, session.aggregateHash) && (capability === null || enforce(windowId, capability, message).allowed);
+    if (!allowed() || firewall(windowId, message, capability, false) === "drop") return;
+    let lifetime = windowLifetimes.get(windowId);
+    if (!lifetime) {
+      lifetime = {};
+      windowLifetimes.set(windowId, lifetime);
+    }
+    handler.handleMessage(windowId, message, (response) => {
+      if (registrations.get(domain) !== registration || services[domain] !== handler || windowLifetimes.get(windowId) !== lifetime || sessions.getEntryByWindowId(windowId) !== session) return;
+      if (!response || typeof response.type !== "string" || !response.type.startsWith(`${domain}.`) || response.type.length <= dot + 1) return;
+      if (allowed()) hooks.sendToNapplet(windowId, response);
+    });
+  }
+  return {
+    handleMessage,
+    destroyWindow(windowId) {
+      windowLifetimes.delete(windowId);
+    },
+    destroy() {
+      windowLifetimes.clear();
+    }
+  };
+}
+
 // src/service-dispatch.ts
 function routeServiceMessage(windowId, message, services, sendToNapplet) {
   if (message.type === "inc.emit") return false;
   const domain = message.type.split(".")[0];
-  const handler = services[domain];
+  const handler = Object.hasOwn(services, domain) ? services[domain] : void 0;
   if (handler) {
     handler.handleMessage(windowId, message, (msg) => sendToNapplet(windowId, msg));
     return true;
@@ -633,12 +674,17 @@ function handleRelaySubscribe(context, windowId, msg, m) {
   const filters = m.filters ?? [];
   if (!subId) return;
   const subKey = `${windowId}:${subId}`;
-  subscriptions.set(subKey, { windowId, filters });
+  const entry = { windowId, filters };
+  subscriptions.set(subKey, entry);
+  const isActive = () => subscriptions.get(subKey) === entry && context.canReadRelay(windowId);
+  const send = (response) => {
+    if (isActive()) hooks.sendToNapplet(windowId, normalizeRelayServiceResponse(response));
+  };
   const seenIds = /* @__PURE__ */ new Set();
   function deliver(event, relayHints) {
     if (seenIds.has(event.id)) return;
     seenIds.add(event.id);
-    if (subscriptions.has(subKey)) {
+    if (isActive()) {
       sendRelayEvent(hooks, windowId, subId, createRelayEventResultWithHints(event, relayHints));
     }
   }
@@ -649,22 +695,16 @@ function handleRelaySubscribe(context, windowId, msg, m) {
   const relayService = relayServiceFrom(context);
   const cacheService = !serviceRegistry["relay"] ? serviceRegistry["cache"] : void 0;
   if (!isShellKind && relayService) {
-    relayService.handleMessage(windowId, msg, (resp) => {
-      if (!subscriptions.has(subKey)) return;
-      hooks.sendToNapplet(windowId, normalizeRelayServiceResponse(resp));
-    });
-    if (cacheService) {
-      cacheService.handleMessage(windowId, msg, (resp) => {
-        if (!subscriptions.has(subKey)) return;
-        hooks.sendToNapplet(windowId, normalizeRelayServiceResponse(resp));
-      });
-    }
+    relayService.handleMessage(windowId, msg, send);
+    if (cacheService && isActive()) cacheService.handleMessage(windowId, msg, send);
+    if (!isActive()) closeRelayBackends(context, windowId, subId, subKey);
     return;
   }
   const relayHint = typeof m.relay === "string" && m.relay.length > 0 ? m.relay : void 0;
-  deliverFromRuntimeBackends(context, windowId, subId, subKey, filters, isShellKind, deliver, relayHint);
+  if (!isActive()) return;
+  deliverFromRuntimeBackends(context, subId, subKey, filters, isShellKind, deliver, send, isActive, relayHint);
 }
-function deliverFromRuntimeBackends(context, windowId, subId, subKey, filters, isShellKind, deliver, relayHint) {
+function deliverFromRuntimeBackends(context, subId, subKey, filters, isShellKind, deliver, send, isActive, relayHint) {
   const { hooks } = context;
   const cache = hooks.cache;
   if (cache?.isAvailable() && !isShellKind) {
@@ -675,7 +715,7 @@ function deliverFromRuntimeBackends(context, windowId, subId, subKey, filters, i
   }
   const pool = hooks.relayPool;
   if (!pool?.isAvailable() && !isShellKind) {
-    hooks.sendToNapplet(windowId, { type: "relay.eose", subId });
+    send({ type: "relay.eose", subId });
     return;
   }
   if (!pool?.isAvailable() || isShellKind) return;
@@ -684,15 +724,16 @@ function deliverFromRuntimeBackends(context, windowId, subId, subKey, filters, i
   const eoseFallbackTimer = setTimeout(() => {
     if (!eoseSent) {
       eoseSent = true;
-      hooks.sendToNapplet(windowId, { type: "relay.eose", subId });
+      send({ type: "relay.eose", subId });
     }
   }, 15e3);
   const subscription = pool.subscribe(filters, (item) => {
+    if (!isActive()) return;
     if (item === "EOSE") {
       clearTimeout(eoseFallbackTimer);
       if (!eoseSent) {
         eoseSent = true;
-        hooks.sendToNapplet(windowId, { type: "relay.eose", subId });
+        send({ type: "relay.eose", subId });
       }
       return;
     }
@@ -710,6 +751,31 @@ function deliverFromRuntimeBackends(context, windowId, subId, subKey, filters, i
     clearTimeout(eoseFallbackTimer);
     subscription.unsubscribe();
   });
+  if (!isActive()) pool.untrackSubscription(subKey);
+}
+function closeRelayBackends(context, windowId, subId, subKey) {
+  const relay = context.serviceRegistry["relay"] ?? context.serviceRegistry["relay-pool"];
+  const cache = !context.serviceRegistry["relay"] ? context.serviceRegistry["cache"] : void 0;
+  for (const service of /* @__PURE__ */ new Set([relay, cache])) {
+    try {
+      service?.handleMessage(windowId, { type: "relay.close", subId }, () => {
+      });
+    } catch {
+    }
+  }
+  try {
+    context.hooks.relayPool?.untrackSubscription(subKey);
+  } catch {
+  }
+}
+function revokeRelaySubscriptions(context, windowId) {
+  const entries = [...context.subscriptions].filter(([, entry]) => entry.windowId === windowId);
+  for (const [key] of entries) context.subscriptions.delete(key);
+  for (const [key] of entries) {
+    const subId = key.slice(windowId.length + 1);
+    closeRelayBackends(context, windowId, subId, key);
+    context.hooks.sendToNapplet(windowId, { type: "relay.closed", subId, reason: "denied: relay:read" });
+  }
 }
 function handleRelayClose(context, windowId, msg, m) {
   const { hooks, subscriptions } = context;
@@ -1850,13 +1916,18 @@ function buildObservation(envelope, windowId, senderCap, sessionRegistry, getFoc
 }
 function createFirewallGate(config) {
   const { firewallState, sessionRegistry, hooks, fireConsent } = config;
-  return function firewallGate(windowId, envelope, senderCap) {
+  return function firewallGate(windowId, envelope, senderCap, respond = true) {
     const obs = buildObservation(envelope, windowId, senderCap, sessionRegistry, hooks.getFocusContext);
     const result = firewallState.evaluate(obs);
     const { decision, action, ruleId, reason } = result;
     const napplet = obs.napplet;
     const opClass = obs.opClass;
     if (decision === "reject" || decision === "prompt") {
+      if (!respond) {
+        hooks.onFirewallEvent?.({ windowId, napplet, opClass, decision, action, ruleId, reason, message: envelope });
+        if (decision === "prompt") fireConsent(windowId, napplet);
+        return "drop";
+      }
       const intentDenial = createIntentPolicyDenial(envelope);
       if (intentDenial) {
         hooks.sendToNapplet(windowId, intentDenial);
@@ -1907,7 +1978,7 @@ function createDenialResponse(envelope, error) {
   const type = denialResponseType(envelope);
   return type ? { type, id, error } : null;
 }
-function createMessageHandler(hooks, sessionRegistry, enforceNap, dispatchNapEnvelope, firewallGate) {
+function createMessageHandler(hooks, sessionRegistry, enforceNap, dispatchNapEnvelope, serviceRouting, firewallGate) {
   return (windowId, msg) => {
     if (typeof msg !== "object" || msg === null || Array.isArray(msg) || !("type" in msg) || typeof msg.type !== "string") return;
     const envelope = msg;
@@ -1915,6 +1986,10 @@ function createMessageHandler(hooks, sessionRegistry, enforceNap, dispatchNapEnv
     if (dotIdx === -1) return;
     if (!sessionRegistry.getEntryByWindowId(windowId)) return;
     const domain = envelope.type.slice(0, dotIdx);
+    if (!serviceRouting.builtInDomains.has(domain)) {
+      serviceRouting.extensions.handleMessage(windowId, envelope);
+      return;
+    }
     if (hooks.isDomainAllowed && !hooks.isDomainAllowed(windowId, domain)) return;
     if (isIdentityOrThemeMessage(envelope) && !createCanonicalDomainResult(envelope)) return;
     const caps = resolveCapabilitiesNap(envelope);
@@ -1967,7 +2042,8 @@ function createRuntimeInstance(context) {
     serviceRegistry,
     sessionRegistry,
     subscriptions,
-    consentHandlerRef
+    consentHandlerRef,
+    extensions
   } = context;
   const undeclaredServiceConsents = /* @__PURE__ */ new Set();
   const attachedServices = /* @__PURE__ */ new Map();
@@ -2031,6 +2107,8 @@ function createRuntimeInstance(context) {
       eventBuffer.bufferAndDeliver(createInjectedEvent(hooks, topic, payload), null);
     },
     destroy() {
+      extensions.destroy();
+      registeredServices.clear();
       for (const name of attachedServices.keys()) detachService(name);
       manifestCache.persist();
       aclState.persist();
@@ -2039,13 +2117,13 @@ function createRuntimeInstance(context) {
       subscriptions.clear();
       incRuntime.clear();
       eventBuffer.clear();
-      registeredServices.clear();
       undeclaredServiceConsents.clear();
     },
     registerConsentHandler(handler) {
       consentHandlerRef.current = handler;
     },
     registerService(name, handler) {
+      registeredServices.delete(name);
       detachService(name);
       serviceRegistry[name] = handler;
       registeredServices.set(name, {
@@ -2056,11 +2134,12 @@ function createRuntimeInstance(context) {
       attachService(name, handler);
     },
     unregisterService(name) {
+      registeredServices.delete(name);
       detachService(name);
       delete serviceRegistry[name];
-      registeredServices.delete(name);
     },
     destroyWindow(windowId) {
+      extensions.destroyWindow(windowId);
       for (const [key] of subscriptions) {
         if (key.startsWith(`${windowId}:`)) {
           subscriptions.delete(key);
@@ -2089,14 +2168,17 @@ function createRuntime(hooks) {
   const serviceRegistry = { ...hooks.services };
   const registeredServices = createRegisteredServices(serviceRegistry);
   const firewallState = createFirewallState(hooks.firewallPersistence);
+  let extensions;
   const sessionRegistry = createSessionRegistry(hooks.onPendingUpdate, (windowId) => {
     firewallState.resetInitBudget(windowId);
+    extensions?.destroyWindow(windowId);
   });
   let incRuntime = null;
   const aclState = createAclState(hooks.aclPersistence, "permissive", (mutation) => {
     if (mutation.type === "revoke" && mutation.capability !== "relay:read") return;
     for (const entry of sessionRegistry.getAllEntries()) {
       if (entry.dTag === mutation.dTag && entry.aggregateHash === mutation.aggregateHash) {
+        revokeRelaySubscriptions({ hooks, serviceRegistry, subscriptions }, entry.windowId);
         incRuntime?.revokeWindow(entry.windowId);
       }
     }
@@ -2153,14 +2235,35 @@ function createRuntime(hooks) {
   firewallState.load();
   manifestCache.load();
   const domainHandlers = createRuntimeDomainHandlers({ hooks, serviceRegistry, sessionRegistry, aclState });
-  const dispatchNapEnvelope = createNapEnvelopeDispatcher({
-    relay: createRelayHandler({ hooks, serviceRegistry, subscriptions, eventBuffer, replayDetector }),
+  const napHandlers = {
+    relay: createRelayHandler({
+      hooks,
+      serviceRegistry,
+      subscriptions,
+      eventBuffer,
+      replayDetector,
+      canReadRelay(windowId) {
+        const entry = sessionRegistry.getEntryByWindowId(windowId);
+        return !!entry && aclState.check("", entry.dTag, entry.aggregateHash, "relay:read");
+      }
+    }),
     identity: createIdentityHandler({ hooks, serviceRegistry }),
     count: createCountHandler({ hooks, serviceRegistry }),
     inc: incRuntime.handleMessage,
     ...domainHandlers
+  };
+  const dispatchNapEnvelope = createNapEnvelopeDispatcher(napHandlers);
+  const builtInDomains = /* @__PURE__ */ new Set([...Object.keys(napHandlers), "shell", "signer"]);
+  extensions = createServiceExtensionRouter({
+    hooks,
+    services: serviceRegistry,
+    registrations: registeredServices,
+    sessions: sessionRegistry,
+    acl: aclState,
+    enforce: enforceNap,
+    firewall: firewallGate
   });
-  const handleMessage = createMessageHandler(hooks, sessionRegistry, enforceNap, dispatchNapEnvelope, firewallGate);
+  const handleMessage = createMessageHandler(hooks, sessionRegistry, enforceNap, dispatchNapEnvelope, { builtInDomains, extensions }, firewallGate);
   return createRuntimeInstance({
     hooks,
     serviceRegistry,
@@ -2174,14 +2277,15 @@ function createRuntime(hooks) {
     firewallState,
     manifestCache,
     consentHandlerRef,
-    handleMessage
+    handleMessage,
+    extensions
   });
 }
 
 // src/index.ts
-import { ALL_CAPABILITIES } from "@kehto/acl/capabilities";
+import { ALL_CAPABILITIES as ALL_CAPABILITIES2 } from "@kehto/acl/capabilities";
 export {
-  ALL_CAPABILITIES,
+  ALL_CAPABILITIES2 as ALL_CAPABILITIES,
   RING_BUFFER_SIZE,
   cleanupNappState,
   createAclState,