@kehto/runtime 0.18.3 → 0.19.0

package/README.md

@@ -12,6 +12,13 @@ Browser-agnostic protocol engine for the napplet protocol.
 pnpm add @kehto/runtime
 ```
 
+## Published Napplet Compatibility
+
+`@kehto/runtime` publishes against `@napplet/core` and `@napplet/nap`
+`>=0.29.0 <0.30.0`. The exact installed convention contracts are core/nap
+0.29.0 from source `dd7b3a728eb9c838b7218fcec7bb7bb00e7cc88b` and release
+`60889f1c2476e063500c7ab6624af6abe0dbcbe5`.
+
 ## Overview
 
 `@kehto/runtime` is Kehto's NIP-5D protocol engine. It owns every incoming napplet message, gates it through the ACL enforcement layer, routes it to the correct NAP handler, and emits the corresponding reply envelope.
@@ -26,12 +33,114 @@ The runtime is built around the current draft dispatch contract from `@napplet/c
 - **relay** — `relay.publish`, `relay.publishEncrypted`, `relay.subscribe`
 - **dm** — `dm.status`, `dm.conversations`, `dm.messages`, `dm.send`, runtime service dispatch
 - **storage** — `storage.get/set/remove/keys` with quota enforcement
-- **theme** — `theme.get`, `theme.changed` fan-out
+- **theme** — `theme.get` and automatic recipient-authorized `theme.changed`
 
 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 publish boundary
+
+The publish path follows draft [NAP-RELAY PR #2 at
+`0be8abce18beb46ca37bd4ddd042f58d30b4eedc`](https://github.com/napplet/naps/pull/2).
+A napplet submits an `EventTemplate`; the runtime obtains the active
+shell-owned signer, signs once, and gives only the resulting `NostrEvent` to
+the relay backend. Success returns exactly one correlated
+`relay.publish.result` with `ok: true`, the full signed `event`, and `eventId`.
+Signing, replay, relay, and service failures return `ok: false` plus `error`
+and are never buffered as successful local publications.
+
+The released `@napplet/nap@0.29.0` SDK accepts `EventTemplate`, while its
+`RelayPublishMessage.event` declaration still says `NostrEvent`; Kehto records
+that mismatch as upstream package drift and follows the NAP wire direction.
+
+## Identity and theme result policy
+
+This runtime follows NAP-IDENTITY and NAP-THEME at `napplet/naps` master
+`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`.
+
+- `identity.getPublicKey` always yields exactly one correlated
+  `identity.getPublicKey.result`; no signer or a signer failure is
+  `pubkey: ""`. Other supported readonly identity operations yield their
+  matching result shapes with safe defaults, while unsupported identity actions
+  are silently ignored.
+- `theme.get` uses a complete three-color result. For denied or unavailable
+  reads, Kehto's explicit policy is one fixed non-sensitive normal result with
+  no `error` field. This reconciles the draft's error-only example without
+  emitting `theme.*.error` or inventing a mixed theme/error payload.
+- The runtime neither accepts nor creates identity/theme subscription messages.
+  Change delivery is host-owned and recipient-gated by the shell bridge; it is
+  not routed through NAP-INC or NAP-INTENT.
+
+Phase 105 adopts the published `@napplet/*` convention package line; archived
+phase records remain history rather than active compatibility guidance.
+
+## NAP-INTENT runtime boundary
+
+Phase 104 implements the draft [NAP-INTENT PR #91 at
+`a718915ddefa2f03a0126579601f59d8bd86f7c4`](https://github.com/napplet/naps/pull/91).
+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 only that a host controller has
+already retained delivery responsibility. The service sends that result before
+starting the retained task; target startup, readiness, reuse, replacement,
+retry, and terminal failure remain private host policy. A ready target receives
+one no-ID `intent.deliver` with the runtime-attested sender, never a visible INC
+carrier or window/lifecycle fields.
+
+The canonical public `Intent*` contracts are the released `@napplet/core` /
+`@napplet/nap` declarations; Kehto retains no local type mirror. An accepted
+result transfers delivery responsibility before a retained task starts, and a
+post-acceptance outcome never creates a second source result.
+
+Phase 105 completed released package adoption and persistent installed-manifest
+controllers for the live Paja and playground hosts.
+
+## NAP-INC Contract
+
+The active INC boundary follows merged
+[`naps/NAP-INC.md`](https://github.com/napplet/naps/blob/6461e4b37c29dc09a20dff35d9515889c4433874/naps/NAP-INC.md)
+on `napplet/naps` master
+`6461e4b37c29dc09a20dff35d9515889c4433874`. The document remains marked
+draft, but the merged path is the protocol authority.
+
+The released projection binding converts a convention query to a text payload
+map before sending `inc.emit`. Runtime `inc-handler` routing then uses an exact
+queryless topic identity, with no query-bearing normalized wire/discovery
+identity, prefix/wildcard/query-aware matching, generic or service-over-INC
+prefix dispatch, or runtime payload-kind inference. The runtime derives the
+**runtime-attested dTag** from the registered source; callers never supply a
+sender, topic delivery excludes its source, and IDs/payloads are opaque.
+
+Channels apply **open-time authorization** only: ACL and target liveness are
+checked at `inc.channel.open`, never per later message. The target receives
+`inc.channel.opened` before the opener result and both sides get symmetric
+handles with `onOpened`, `on`, and `onClosed`; early events and terminal closure
+are retained in order, bounded overflow closes the channel, and close or endpoint
+destruction tears it down deterministically. `channel.list` is informational
+only. Track draft follow-up through
+[`kehto/web#203`](https://github.com/kehto/web/issues/203) and [its upstream
+resolution reply](https://github.com/kehto/web/issues/203#issuecomment-5060904495),
+not the obsolete opener-only model.
+
+This is INC documentation only. **Phase 104** owns every public #91 NAP-INTENT
+binding/resolution/delivery change; **Phase 105** records the completed released
+package adoption. Historical changelogs and archived planning are preserved
+records, not targets for active-surface edits.
+
 Everything plugs into a single factory, `createRuntime()`, via a `RuntimeAdapter` hook bag — persistence, relay pool, auth, services, and so on. No DOM, no postMessage, no localStorage: those live in `@kehto/shell`.
 
+`RelayPoolAdapter.publish()` may return a promise. The runtime waits for that
+promise before reporting publish success, buffers only successful publishes,
+and releases failed replay reservations so a deterministic signed event can be
+retried without allowing concurrent duplicate publication.
+`publishToScopedRelay()` may similarly return `Promise<boolean>` when a host
+needs transport settlement before reporting the scoped publication outcome.
+
 ## Quick Start
 
 ```ts

package/dist/index.d.ts

@@ -205,8 +205,13 @@ interface RelayPoolAdapter {
      * Returns a handle that can cancel the subscription.
      */
     subscribe(filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void, relayUrls?: string[]): RelaySubscriptionHandle;
-    /** Publish an event to relays. */
-    publish(event: NostrEvent): void;
+    /**
+     * Publish an event to relays.
+     *
+     * Async adapters return a promise that settles only after the transport has
+     * accepted or rejected the publish.
+     */
+    publish(event: NostrEvent): void | Promise<void>;
     /** Select relay URLs appropriate for the given filters. */
     selectRelayTier(filters: NostrFilter[]): string[];
     /** Track a subscription key for lifecycle management. */
@@ -217,8 +222,13 @@ interface RelayPoolAdapter {
     openScopedRelay(windowId: string, relayUrl: string, subId: string, filters: NostrFilter[], sendToNapplet: SendToNapplet): void;
     /** Close a scoped relay connection. */
     closeScopedRelay(windowId: string): void;
-    /** Publish to a scoped relay. Returns false if no active scoped relay. */
-    publishToScopedRelay(windowId: string, event: NostrEvent): boolean;
+    /**
+     * Publish to a scoped relay.
+     *
+     * Async adapters settle the returned promise after transport acceptance.
+     * Returns false if no active scoped relay or publication fails.
+     */
+    publishToScopedRelay(windowId: string, event: NostrEvent): boolean | Promise<boolean>;
     /** Whether a relay pool is available. */
     isAvailable(): boolean;
 }
@@ -517,6 +527,40 @@ interface AclEntryExternal {
     blocked: boolean;
     stateQuota?: number;
 }
+/**
+ * Narrow runtime-owned access granted to a registered service.
+ *
+ * The context exposes current immutable identity values and policy-aware target
+ * delivery without exposing the mutable session registry, ACL state, adapter
+ * hooks, or raw transport.
+ */
+interface ServiceRuntimeContext {
+    /**
+     * Resolve a currently registered window to its authenticated napplet dTag.
+     *
+     * @param windowId - Internal live window identifier.
+     * @returns The authenticated dTag, or `undefined` when no live session exists.
+     */
+    resolveDTag(windowId: string): string | undefined;
+    /**
+     * List current registered window identifiers.
+     *
+     * @returns A fresh frozen snapshot of live window identifiers.
+     */
+    listWindowIds(): readonly string[];
+    /**
+     * 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.
+     *
+     * @param windowId - Intended live recipient window.
+     * @param message - Runtime-originated NIP-5D envelope.
+     * @returns `true` only when the message was delivered to the adapter.
+     */
+    sendToEligibleNapplet(windowId: string, message: NappletMessage): boolean;
+}
 /**
  * Handler for service-specific messages from napplets.
  * Services receive NIP-5D NappletMessage envelopes and respond via the `send` callback.
@@ -538,6 +582,14 @@ interface AclEntryExternal {
 interface ServiceHandler {
     /** Metadata describing this service. */
     descriptor: ServiceDescriptor;
+    /**
+     * Attach this handler to one runtime instance.
+     *
+     * @param context - Narrow runtime-owned identity and recipient-send access.
+     */
+    onRegistered?(context: ServiceRuntimeContext): void;
+    /** Release runtime attachment state when replaced, unregistered, or destroyed. */
+    onUnregistered?(): void;
     /**
      * Handle a NIP-5D envelope from a napplet.
      *
@@ -623,6 +675,12 @@ interface RuntimeConfigOverrides {
 interface RuntimeAdapter {
     /** Send a NIP-01 message to a napplet by windowId. */
     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`.
+     */
+    isDomainAllowed?: (windowId: string, domain: string) => boolean;
     /**
      * Relay pool operations.
      * Optional when a 'relay' or 'relay-pool' service is registered via
@@ -877,6 +935,17 @@ interface SessionRegistry {
     getEntry(pubkey: string): SessionEntry | undefined;
     /** Get the windowId for a napplet pubkey. */
     getWindowId(pubkey: string): string | undefined;
+    /**
+     * Resolve an unambiguous live napplet dTag to its internal window ID.
+     *
+     * A duplicate dTag fails closed rather than selecting an arbitrary session.
+     * Window IDs and pubkeys remain internal transport identities and never
+     * resolve through this lookup.
+     *
+     * @param dTag - Runtime-attested napplet dTag
+     * @returns The sole owning window ID, or undefined when missing or ambiguous
+     */
+    getWindowIdByDTag(dTag: string): string | undefined;
     /** Check if a windowId has a registered napplet. */
     isRegistered(windowId: string): boolean;
     /** Get all registered napplet entries. */
@@ -924,6 +993,19 @@ declare const createNappKeyRegistry: typeof createSessionRegistry;
  * AclPersistence. No localStorage or DOM references.
  */
 
+/** An ACL authority change that can invalidate runtime-owned routes. */
+type AclMutation = {
+    readonly type: 'revoke';
+    readonly dTag: string;
+    readonly aggregateHash: string;
+    readonly capability: Capability;
+} | {
+    readonly type: 'block';
+    readonly dTag: string;
+    readonly aggregateHash: string;
+};
+/** Receives synchronous ACL authority changes after persistence succeeds. */
+type AclMutationObserver = (mutation: AclMutation) => void;
 /**
  * ACL state container — wraps @kehto/acl's pure functions with
  * persistence and a convenient imperative API.
@@ -955,6 +1037,7 @@ interface AclStateContainer {
  *
  * @param persistence - Storage backend for ACL state
  * @param defaultPolicy - Default ACL policy for unknown identities
+ * @param onMutation - Internal runtime observer for revoke and block facts
  * @returns An AclStateContainer instance
  *
  * @example
@@ -963,7 +1046,7 @@ interface AclStateContainer {
  * aclState.load();
  * ```
  */
-declare function createAclState(persistence: AclPersistence, defaultPolicy?: 'permissive' | 'restrictive'): AclStateContainer;
+declare function createAclState(persistence: AclPersistence, defaultPolicy?: 'permissive' | 'restrictive', onMutation?: AclMutationObserver): AclStateContainer;
 
 /**
  * firewall-state.ts — Firewall state container with persistence hooks.
@@ -1142,10 +1225,31 @@ declare function createManifestCache(persistence: ManifestPersistence): Manifest
  */
 interface ReplayDetector {
     /**
-     * Check if an event should be rejected as a replay.
-     * Returns null if event is valid, or a string reason if it should be rejected.
+     * Check if an event should be rejected as a replay and record it as processed.
+     * Returns null if the event is valid, or a string reason if it should be rejected.
      */
     check(event: NostrEvent): string | null;
+    /**
+     * Check an event and atomically reserve its ID for pending processing.
+     * Call {@link commit} after processing succeeds or {@link release} after it fails.
+     *
+     * @param event - Signed event whose ID should be reserved
+     * @returns null if reserved, or a string reason if it should be rejected
+     */
+    reserve(event: NostrEvent): string | null;
+    /**
+     * Commit a pending reservation as successfully processed.
+     *
+     * @param eventId - Reserved signed event ID
+     */
+    commit(eventId: string): void;
+    /**
+     * Release a pending reservation so a failed operation can be retried.
+     * Committed event IDs are never removed by this method.
+     *
+     * @param eventId - Reserved signed event ID
+     */
+    release(eventId: string): void;
     /** Clear all tracked event IDs. */
     clear(): void;
 }
@@ -1447,11 +1551,9 @@ declare function cleanupNappState(pubkey: string, dTag: string, aggregateHash: s
 /**
  * Route a NappletMessage envelope to the matching service handler.
  *
- * NAP-domain services are routed by the domain prefix of message.type
- * (e.g., 'signer.signEvent' -> 'signer' service).
- *
- * INC-routed services receive inc.emit messages and are routed by the
- * topic prefix before ':' (e.g., topic 'audio:play' -> 'audio' service).
+ * Direct NAP-domain services are routed by the domain in their wire
+ * message.type (e.g., 'signer.signEvent' -> 'signer' service). INC messages
+ * are owned by the INC runtime; their topic values are opaque here.
  *
  * Returns true if a service handled the message, false otherwise.
  *
@@ -1484,4 +1586,4 @@ declare function routeServiceMessage(windowId: string, message: NappletMessage,
  */
 declare function notifyServiceWindowDestroyed(windowId: string, services: ServiceRegistry): void;
 
-export { type AclCheckEvent, type AclChecker, type AclEntryExternal, type AclPersistence, type AclStateContainer, type AuthAdapter, type CacheAdapter, type CompatibilityReport, type ConfigAdapter, type ConsentHandler, type ConsentRequest, type CryptoAdapter, type DmAdapter, type EnforceConfig, type EnforceResult, type EventBuffer, type FirewallEvent, type FirewallPersistence, type FirewallStateContainer, type GuidPersistence, type HashVerifierAdapter, type HotkeyAdapter, type IdentityResolver, type ManifestCache, type ManifestCacheEntry, type ManifestPersistence, type NapEnforceConfig, type NappKeyEntry, type NappKeyRegistry, type PendingUpdate, type PendingUpdateNotifier, RING_BUFFER_SIZE, type RelayConfigAdapter, type RelayEventCarrier, type RelayEventResult, type RelayEventSidecar, type RelayPoolAdapter, type RelaySubscriptionHandle, type ReplayDetector, type Runtime, type RuntimeAdapter, type RuntimeConfigOverrides, type SendToNapplet, type ServiceDescriptor, type ServiceHandler, type ServiceInfo, type ServiceRegistry, type SessionEntry, type SessionRegistry, type ShellSecretPersistence, type Signer, type StatePersistence, type SubscriptionEntry, type VerificationCacheEntry, type WindowManagerAdapter, cleanupNappState, createAclState, createEnforceGate, createEventBuffer, createFirewallState, createManifestCache, createNapEnforceGate, createNappKeyRegistry, createRelayEventResult, createRelayEventResultWithHints, createReplayDetector, createRuntime, createSessionRegistry, formatDenialReason, handleStorageNap, matchesAnyFilter, matchesFilter, notifyServiceWindowDestroyed, relayEventResultFromCarrier, routeServiceMessage };
+export { type AclCheckEvent, type AclChecker, type AclEntryExternal, type AclMutation, type AclMutationObserver, type AclPersistence, type AclStateContainer, type AuthAdapter, type CacheAdapter, type CompatibilityReport, type ConfigAdapter, type ConsentHandler, type ConsentRequest, type CryptoAdapter, type DmAdapter, type EnforceConfig, type EnforceResult, type EventBuffer, type FirewallEvent, type FirewallPersistence, type FirewallStateContainer, type GuidPersistence, type HashVerifierAdapter, type HotkeyAdapter, type IdentityResolver, type ManifestCache, type ManifestCacheEntry, type ManifestPersistence, type NapEnforceConfig, type NappKeyEntry, type NappKeyRegistry, type PendingUpdate, type PendingUpdateNotifier, RING_BUFFER_SIZE, type RelayConfigAdapter, type RelayEventCarrier, type RelayEventResult, type RelayEventSidecar, type RelayPoolAdapter, type RelaySubscriptionHandle, type ReplayDetector, type Runtime, type RuntimeAdapter, type RuntimeConfigOverrides, type SendToNapplet, type ServiceDescriptor, type ServiceHandler, type ServiceInfo, type ServiceRegistry, type ServiceRuntimeContext, type SessionEntry, type SessionRegistry, type ShellSecretPersistence, type Signer, type StatePersistence, type SubscriptionEntry, type VerificationCacheEntry, type WindowManagerAdapter, cleanupNappState, createAclState, createEnforceGate, createEventBuffer, createFirewallState, createManifestCache, createNapEnforceGate, createNappKeyRegistry, createRelayEventResult, createRelayEventResultWithHints, createReplayDetector, createRuntime, createSessionRegistry, formatDenialReason, handleStorageNap, matchesAnyFilter, matchesFilter, notifyServiceWindowDestroyed, relayEventResultFromCarrier, routeServiceMessage };