@kehto/runtime 0.24.0 → 0.25.0

package/README.md

@@ -84,21 +84,17 @@ phase records remain history rather than active compatibility guidance.
 
 ## NAP-INTENT runtime boundary
 
-Kehto implements merged [NAP-INTENT at
-`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`](https://github.com/napplet/naps/blob/5ac0490461ca6fec2f0d2e45b4835cf9bc08de24/naps/NAP-INTENT.md).
-The runtime accepts only source-side `intent.invoke`, `intent.available`, and
-`intent.handlers` requests. It validates the exact queryless
-`napplet:<archetype>/<action>` identity, derives the sender dTag from the live
-authenticated session, and shapes policy denials as sanctioned result
-envelopes without exposing ACL or firewall details.
-
-Registered services receive a frozen `ServiceRuntimeContext`: current dTag
-resolution, a frozen live-window snapshot, and recipient-policy-aware sends.
-An `intent.invoke.result` with `ok: true` means a host controller selected and
-readied the verified target and dispatched its convention. The final result
-includes `handled`, `handler`, `windowId`, and `convention`. The target receives
-one runtime-attested `inc.event` carrying that queryless convention and opaque
-payload; `intent.deliver` is not part of the merged contract.
+Kehto follows [NAP-INTENT PR #106](https://github.com/napplet/naps/blob/fc121fc264615482143eda86125863d2e1f741a2/naps/NAP-INTENT.md) at `fc121fc264615482143eda86125863d2e1f741a2`. The runtime admits source-side `intent.invoke`,
+`intent.available`, and `intent.handlers` through the authenticated session and
+ACL/firewall boundary. Services validate the normalized queryless convention and
+resolve the sender's opaque catalog ID from the trusted source window.
+
+Registered services receive a frozen `ServiceRuntimeContext` with live-window
+facts and recipient-policy-aware sends. Success acknowledges retained delivery
+responsibility with `ok`, `archetype`, `action`, `convention`, and `handler`.
+After current target readiness, the controller sends one `intent.deliver` with
+parent-attested sender and opaque payload. Completion belongs to host observation,
+not another source result. No INC carrier is required.
 
 ## NAP-OUTBOX denial boundary
 
@@ -109,8 +105,9 @@ the protocol-defined correlated result wire: `outbox.query.result` with
 `events: []` and `error`. The runtime does not synthesize an
 `outbox.query.error` message.
 
-The canonical public `Intent*` contracts are the released `@napplet/core` /
-`@napplet/nap` declarations; Kehto retains no local type mirror.
+The installed `@napplet/nap@0.32.0` contract trails PR #106. The bounded local
+`@kehto/services` intent types and their removal condition are documented in
+[conformance policy](https://github.com/kehto/web/blob/main/docs/policies/NIP-5D-CONFORMANCE.md).
 
 Phase 105 completed released package adoption and persistent installed-manifest
 controllers for the live Paja and playground hosts.
@@ -226,10 +223,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.
 
@@ -247,3 +258,7 @@ Generated API module: `docs/api/modules/_kehto_runtime.html` (run `pnpm docs:api
 ## License
 
 MIT
+
+## GAMEPAD integration
+
+This non-normative guidance defers to the living [NAP-GAMEPAD](https://github.com/napplet/naps/pull/108). Services export `createGamepadService` and `browserGamepadOptions`; shell exports `denyNappletControllerAccess`. Paja and the playground register one host reader and deny 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](https://github.com/kehto/web/blob/main/docs/gamepad.md).

package/dist/index.d.ts

@@ -566,9 +566,9 @@ interface ServiceRuntimeContext {
     /**
      * Send a runtime-originated message after current recipient policy checks.
      *
-     * The message must have a recipient capability mapping. The target must be a
-     * live session whose immutable domain environment and current ACL grant both
-     * permit the message.
+     * The target must be a live source-bound session whose immutable environment
+     * exposes the domain. Mapped recipient capabilities also require their current
+     * ACL grant. GAMEPAD state has no invented recipient capability mapping.
      *
      * @param windowId - Intended live recipient window.
      * @param message - Runtime-originated NIP-5D envelope.
@@ -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;
@@ -1616,6 +1657,7 @@ function cleanupNappState(pubkey, dTag, aggregateHash, statePersistence) {
 // src/domain-handlers.ts
 function createRuntimeDomainHandlers(context) {
   return {
+    gamepad: (windowId, msg) => handleServiceOnlyMessage(context, "gamepad", windowId, msg),
     storage: (windowId, msg) => handleStorageMessage(context, windowId, msg),
     media: (windowId, msg) => handleMediaMessage(context, windowId, msg),
     keys: (windowId, msg) => handleKeysMessage(context, windowId, msg),
@@ -1766,6 +1808,7 @@ function createNapEnvelopeDispatcher(handlers) {
   const adapt = (handler) => (msg) => {
     if (currentWindowId !== null) handler(currentWindowId, msg);
   };
+  napDispatch.registerNap("gamepad", adapt(handlers.gamepad));
   napDispatch.registerNap("relay", adapt(handlers.relay));
   napDispatch.registerNap("identity", adapt(handlers.identity));
   napDispatch.registerNap("count", adapt(handlers.count));
@@ -1848,13 +1891,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);
@@ -1905,14 +1953,18 @@ 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 || !("type" in msg)) return;
+    if (typeof msg !== "object" || msg === null || Array.isArray(msg) || !("type" in msg) || typeof msg.type !== "string") return;
     const envelope = msg;
     const dotIdx = envelope.type.indexOf(".");
     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);
@@ -1965,7 +2017,8 @@ function createRuntimeInstance(context) {
     serviceRegistry,
     sessionRegistry,
     subscriptions,
-    consentHandlerRef
+    consentHandlerRef,
+    extensions
   } = context;
   const undeclaredServiceConsents = /* @__PURE__ */ new Set();
   const attachedServices = /* @__PURE__ */ new Map();
@@ -1993,8 +2046,8 @@ function createRuntimeInstance(context) {
       try {
         if (isDomainAllowed && !isDomainAllowed(windowId, domain)) return false;
         const { recipientCap } = resolveCapabilitiesNap(message);
-        if (!recipientCap) return false;
-        if (!aclState.check("", entry.dTag, entry.aggregateHash, recipientCap)) {
+        if (!recipientCap && message.type !== "gamepad.state") return false;
+        if (recipientCap && !aclState.check("", entry.dTag, entry.aggregateHash, recipientCap)) {
           return false;
         }
         sendToNapplet(windowId, message);
@@ -2029,6 +2082,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();
@@ -2037,13 +2092,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, {
@@ -2054,11 +2109,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);
@@ -2087,8 +2143,10 @@ 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) => {
@@ -2151,14 +2209,25 @@ function createRuntime(hooks) {
   firewallState.load();
   manifestCache.load();
   const domainHandlers = createRuntimeDomainHandlers({ hooks, serviceRegistry, sessionRegistry, aclState });
-  const dispatchNapEnvelope = createNapEnvelopeDispatcher({
+  const napHandlers = {
     relay: createRelayHandler({ hooks, serviceRegistry, subscriptions, eventBuffer, replayDetector }),
     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,
@@ -2172,14 +2241,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,