@kehto/runtime 0.2.0 → 0.5.0

package/README.md

@@ -2,6 +2,10 @@
 
 Browser-agnostic protocol engine for the napplet protocol.
 
+> **Alpha status:** Kehto is an early runtime implementation for a draft NIP-5D
+> protocol. NUB contracts and runtime APIs are not final; treat this package as
+> current implementation guidance, not as a stable protocol guarantee.
+
 ## Install
 
 ```bash
@@ -10,9 +14,9 @@ pnpm add @kehto/runtime
 
 ## Overview
 
-`@kehto/runtime` is the canonical v1.2 NIP-5D protocol engine. It owns every incoming napplet message, gates it through the ACL enforcement layer, routes it to the correct NUB handler, and emits the corresponding reply envelope.
+`@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 NUB handler, and emits the corresponding reply envelope.
 
-The runtime is built around the canonical dispatch contract from `@napplet/core` — `createDispatch()` + `registerNub()` — so routing is declarative, not a hand-rolled switch. Covers all eight canonical NIP-5D domains end-to-end:
+The runtime is built around the current draft dispatch contract from `@napplet/core` — `createDispatch()` + `registerNub()` — so routing is declarative, not a hand-rolled switch. It covers the NIP-5D domains currently supported by Kehto:
 
 - **identity** — `identity.getProfile`, `identity.getFollows`, `identity.getPublicKey`, …
 - **ifc** — `ifc.channel.*`, `ifc.emit`, cross-napplet pub/sub
@@ -40,7 +44,7 @@ const runtime = createRuntime({
   // ... further adapter hooks
 });
 
-// Incoming canonical v1.2 envelope from a napplet:
+// Incoming NIP-5D draft envelope from a napplet:
 runtime.handleMessage('window-1', {
   type: 'relay.publish',
   id: 'evt-42',
@@ -51,52 +55,53 @@ runtime.handleMessage('window-1', {
 ## Public API
 
 ### Runtime factory
-- [`createRuntime`](../../docs/api/functions/_kehto_runtime.createRuntime.html) — primary entry point; `Runtime` interface type
+- `createRuntime` — primary entry point; `Runtime` interface type
 
 ### Enforcement gate
-- [`createEnforceGate`](../../docs/api/functions/_kehto_runtime.createEnforceGate.html) — legacy pubkey-keyed ACL gate
-- [`createNubEnforceGate`](../../docs/api/functions/_kehto_runtime.createNubEnforceGate.html) — NIP-5D windowId-keyed ACL gate
-- [`resolveCapabilitiesNub`](../../docs/api/functions/_kehto_runtime.resolveCapabilitiesNub.html) — map a NIP-5D envelope to required capabilities (re-exported from `@kehto/acl`)
-- [`formatDenialReason`](../../docs/api/functions/_kehto_runtime.formatDenialReason.html) — `denied: <capability>` canonical string
+- `createEnforceGate` — legacy pubkey-keyed ACL gate
+- `createNubEnforceGate` — NIP-5D windowId-keyed ACL gate
+- `resolveCapabilitiesNub` — map a NIP-5D envelope to required capabilities (re-exported from `@kehto/acl`)
+- `formatDenialReason` — `denied: <capability>` canonical string
 
 ### Session registry
-- [`createSessionRegistry`](../../docs/api/functions/_kehto_runtime.createSessionRegistry.html) — bidirectional windowId ↔ `SessionEntry` store
+- `createSessionRegistry` — bidirectional windowId ↔ `SessionEntry` store
 - `createNappKeyRegistry` — deprecated alias retained for v1.1 migration consumers
 
 ### ACL state container
-- [`createAclState`](../../docs/api/functions/_kehto_runtime.createAclState.html) — persistence-backed wrapper around `@kehto/acl` state
+- `createAclState` — persistence-backed wrapper around `@kehto/acl` state
 
 ### Manifest cache
-- [`createManifestCache`](../../docs/api/functions/_kehto_runtime.createManifestCache.html) — NIP-5A aggregate-hash cache with persistence hooks
+- `createManifestCache` — NIP-5A aggregate-hash cache with persistence hooks
 
 ### Replay detection
-- [`createReplayDetector`](../../docs/api/functions/_kehto_runtime.createReplayDetector.html) — duplicate-event + timestamp-window guard
+- `createReplayDetector` — duplicate-event + timestamp-window guard
 
 ### Event buffer
-- [`createEventBuffer`](../../docs/api/functions/_kehto_runtime.createEventBuffer.html) — ring buffer with subscription delivery
-- [`matchesFilter`](../../docs/api/functions/_kehto_runtime.matchesFilter.html), [`matchesAnyFilter`](../../docs/api/functions/_kehto_runtime.matchesAnyFilter.html) — pure NIP-01 filter helpers
+- `createEventBuffer` — ring buffer with subscription delivery
+- `matchesFilter`, `matchesAnyFilter` — pure NIP-01 filter helpers
 - `RING_BUFFER_SIZE` — default ring buffer capacity constant
 
 ### State handler
-- [`handleStorageNub`](../../docs/api/functions/_kehto_runtime.handleStorageNub.html) — canonical `storage.*` NIP-5D handler
-- [`cleanupNappState`](../../docs/api/functions/_kehto_runtime.cleanupNappState.html) — remove persisted state when a napplet window closes
+- `handleStorageNub` — canonical `storage.*` NIP-5D handler
+- `cleanupNappState` — remove persisted state when a napplet window closes
 
 ### Service dispatch
-- [`routeServiceMessage`](../../docs/api/functions/_kehto_runtime.routeServiceMessage.html) — domain-prefix router into the service registry
-- [`notifyServiceWindowDestroyed`](../../docs/api/functions/_kehto_runtime.notifyServiceWindowDestroyed.html) — lifecycle fan-out to every service handler
+- `routeServiceMessage` — domain-prefix router into the service registry
+- `notifyServiceWindowDestroyed` — lifecycle fan-out to every service handler
 
 ### 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.
 
 ### Compat re-exports (DRIFT-CORE-06)
 
-Retained for v1.1 migration consumers; new integrations should use canonical NIP-5D envelope types from `@napplet/core`. Slated for removal once upstream restores those exports.
+Retained for migration consumers; new integrations should use current NIP-5D envelope types from `@napplet/core`. Slated for removal once upstream restores those exports.
 
 Re-exported constants cover the v1.1 bus-kind enum, auth event kind, shell bridge URI, protocol version string, the full capability list, destructive-kind set, and the replay window seconds. Re-exported types cover the v1.1 capability union, bus-kind numeric union, and service descriptor shape. See the typedoc API reference below for the exact identifier list and current numeric values.
 
 ## API Reference
 
-Full API reference: [docs/api/@kehto/runtime/](../../docs/api/modules/_kehto_runtime.html) (generated via `pnpm docs:api`).
+Full package docs: [`docs/packages/runtime.md`](../../docs/packages/runtime.md).
+Generated API module: `docs/api/modules/_kehto_runtime.html` (run `pnpm docs:api`).
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NappletMessage, NostrEvent, NostrFilter } from '@napplet/core';
+import { NappletMessage, NostrEvent, EventTemplate, NostrFilter } from '@napplet/core';
 export { NappletMessage } from '@napplet/core';
 import { Capability } from '@kehto/acl/capabilities';
 export { ALL_CAPABILITIES, Capability } from '@kehto/acl/capabilities';
@@ -12,6 +12,13 @@ export { NubMessage, resolveCapabilitiesNub } from '@kehto/acl';
  * to host napplets. No DOM types, no browser APIs.
  */
 
+/**
+ * A napplet class identifier. `null` is the permissive default (no class).
+ * provisional — mirrors packages/shell/src/types/internal-class.ts::NappletClass;
+ * converges on @napplet/nub/class@^0.3.0 publish. Runtime MUST NOT import
+ * from shell (module-boundary), so this duplicate lives here.
+ */
+type NappletClass = string | null;
 /**
  * Event emitted on every ACL enforcement check.
  *
@@ -39,11 +46,19 @@ interface AclCheckEvent {
     decision: 'allow' | 'deny';
     /** The triggering message, if available. Accepts NIP-01 arrays or NIP-5D NappletMessage envelopes. */
     message?: unknown[] | NappletMessage;
+    /**
+     * Why the decision was reached (v1.7 CLASS-03 / D7). Optional for
+     * backwards compatibility with pre-v1.7 audit consumers.
+     *   'allowed'             -> decision === 'allow'
+     *   'capability-missing'  -> decision === 'deny' (capability lookup failed)
+     *   'class-forbidden'     -> decision === 'deny' (class pre-filter refused)
+     */
+    reason?: 'allowed' | 'capability-missing' | 'class-forbidden';
 }
 /**
  * Abstract message sender — the runtime calls this to send messages
  * back to a specific napplet. The transport layer (postMessage, WebSocket,
- * IPC channel, etc.) is the implementor's concern.
+ * host bridge channel, etc.) is the implementor's concern.
  *
  * Accepts both NIP-01 array format (legacy) and NIP-5D NappletMessage envelope format.
  *
@@ -95,7 +110,7 @@ interface CacheAdapter {
 /** NIP-07 compatible signer interface — minimal methods the runtime needs. */
 interface Signer {
     getPublicKey?(): string | Promise<string>;
-    signEvent?(event: NostrEvent): Promise<NostrEvent>;
+    signEvent?(event: NostrEvent | EventTemplate): Promise<NostrEvent>;
     getRelays?(): Record<string, {
         read: boolean;
         write: boolean;
@@ -375,11 +390,18 @@ interface SessionEntry {
     /** Persistent GUID for this iframe instance, assigned by the runtime. Survives page reloads. */
     instanceId: string;
     /**
-     * How session identity was established.
-     * 'source' = NIP-5D (identity registered at iframe creation via originRegistry).
-     * 'auth' = legacy AUTH handshake (pubkey is the derived keypair pubkey).
+     * How session identity was established (RENAME-01, v1.8 Phase 42).
+     * 'nip-5d' = identity registered at iframe creation via originRegistry (canonical NIP-5D path).
+     * 'legacy-auth' = legacy AUTH handshake (pubkey is the derived keypair pubkey).
+     * Renamed from `identitySource: 'auth' | 'source'` in v1.8; see .changeset/v1-8-rename-01-session-provenance.md.
      */
-    identitySource: 'auth' | 'source';
+    provenance: 'nip-5d' | 'legacy-auth';
+    /**
+     * Class posture resolved synchronously at iframe creation (CLASS-02).
+     * `null` is the permissive default (D2). Class tokens like 'class-1' /
+     * 'class-2' are NUB-defined. See packages/shell/src/types/internal-class.ts.
+     */
+    class: NappletClass;
 }
 /** @deprecated Use SessionEntry. Will be removed in v0.9.0. */
 type NappKeyEntry = SessionEntry;
@@ -505,7 +527,7 @@ interface RuntimeConfigOverrides {
  *
  * This is the primary integration point. A browser shell implements these
  * by wrapping postMessage, localStorage, and relay pool libraries.
- * A CLI or server shell could implement them with IPC channels, file
+ * A CLI or server shell could implement them with host bridge channels, file
  * storage, and direct WebSocket connections.
  *
  * @example
@@ -626,26 +648,22 @@ interface RuntimeAdapter {
     getConfigOverrides?(): RuntimeConfigOverrides;
 }
 
-/**
- * enforce.ts — Single ACL enforcement gate for the NIP-5D runtime.
- *
- * All NIP-5D NappletMessage envelopes pass through createNubEnforceGate()
- * before any handler acts. resolveCapabilitiesNub() (re-exported from
- * @kehto/acl) maps NUB message types to required capabilities. No NIP-01
- * dispatch path remains — v1.4 Phase 24 DRIFT-02 deleted the legacy
- * capability-resolution function along with its dead kind + topic
- * dispatch table.
- */
-
 /**
  * Result of an enforcement check.
  *
  * @param allowed - Whether the capability check passed
  * @param capability - The capability that was checked (human-readable string)
+ * @param reason - Why the decision was reached (v1.7 CLASS-03 / D7). Always set on return.
  */
 interface EnforceResult {
     allowed: boolean;
     capability: Capability;
+    /**
+     * Why the decision was reached (v1.7 CLASS-03 / D7). Always set on the
+     * return path. Distinct from AclCheckEvent.reason (which is optional for
+     * backwards compat on the audit surface).
+     */
+    reason: 'allowed' | 'capability-missing' | 'class-forbidden';
 }
 /**
  * Identity lookup function type — resolves a pubkey to its full identity.
@@ -699,7 +717,9 @@ declare function createEnforceGate(config: EnforceConfig): (pubkey: string, capa
  * Uses windowId for identity resolution instead of pubkey (which is '' in NIP-5D sessions).
  *
  * @param checkAcl - The ACL check function
- * @param resolveIdentityByWindowId - Maps windowId to identity (dTag, aggregateHash)
+ * @param resolveIdentityByWindowId - Maps windowId to identity (dTag, aggregateHash, class). Returns
+ *   class posture inline (v1.7 CLASS-03) so the NUB gate can pre-filter class-forbidden capabilities
+ *   before consulting the ACL check. null class = permissive default (D2).
  * @param onAclCheck - Optional audit callback, called on every enforceNub() check
  */
 interface NubEnforceConfig {
@@ -707,6 +727,7 @@ interface NubEnforceConfig {
     resolveIdentityByWindowId: (windowId: string) => {
         dTag: string;
         aggregateHash: string;
+        class: NappletClass;
     } | undefined;
     onAclCheck?: (event: AclCheckEvent) => void;
 }
@@ -745,16 +766,6 @@ declare function createNubEnforceGate(config: NubEnforceConfig): (windowId: stri
  */
 declare function formatDenialReason(capability: Capability): string;
 
-/**
- * SessionRegistry — windowId to verified napplet pubkey bidirectional mapping.
- *
- * After a successful AUTH handshake, the runtime registers the napplet's
- * verified pubkey here. Both mappings are kept in sync.
- *
- * Unlike the shell singleton version, this is a factory that accepts
- * an optional notifier callback instead of using window.dispatchEvent.
- */
-
 /**
  * Bidirectional registry mapping windowIds to verified napplet pubkeys.
  * Maintained by the runtime after successful AUTH handshakes.
@@ -1058,17 +1069,6 @@ interface EventBuffer {
  */
 declare function createEventBuffer(sendToNapplet: SendToNapplet, sessionRegistry: SessionRegistry, enforce: (pubkey: string, capability: Capability, message?: unknown[]) => EnforceResult, subscriptions: Map<string, SubscriptionEntry>, getBufferSize?: () => number): EventBuffer;
 
-/**
- * runtime.ts — The napplet protocol engine factory.
- *
- * createRuntime(hooks) creates the complete protocol engine that handles
- * NIP-5D NUB domain dispatch, ACL enforcement, subscription lifecycle,
- * signer proxying, and shell command routing.
- *
- * No browser APIs. No DOM. No localStorage. No postMessage.
- * All I/O is delegated to RuntimeAdapter.
- */
-
 /**
  * The napplet protocol engine — handles NIP-5D NUB domain dispatch,
  * ACL enforcement, subscription lifecycle.
@@ -1149,25 +1149,25 @@ declare function createRuntime(hooks: RuntimeAdapter): Runtime;
  * state-handler.ts — Storage NUB request handler using persistence hooks.
  *
  * Handles napplet storage operations (get, set, remove, keys) via the
- * canonical `@napplet/nub-storage` NIP-5D envelope surface. Delegates
+ * canonical `@napplet/nub/storage` NIP-5D envelope surface. Delegates
  * storage to StatePersistence. No localStorage, no legacy NIP-01 dispatch.
  */
 
 /**
  * Handle a NIP-5D NUB storage message from a napplet.
- * Routes to the canonical four `@napplet/nub-storage` actions:
+ * Routes to the canonical four `@napplet/nub/storage` actions:
  *   - `storage.get`    → `storage.get.result`    `{ value: string | null }`
  *   - `storage.set`    → `storage.set.result`    `{ ok: boolean }` (canonical only checks `error`)
  *   - `storage.remove` → `storage.remove.result` `{ ok: boolean }`
  *   - `storage.keys`   → `storage.keys.result`   `{ keys: string[] }`
  *
- * `storage.clear` is NOT in the canonical `@napplet/nub-storage` union (it was a
- * kehto unilateral extension); it now produces a `storage.clear.error` envelope.
- * Internal lifecycle cleanup still uses the `cleanupNappState()` helper below —
- * it is not napplet-reachable.
+ * `storage.clear` is NOT in the canonical `@napplet/nub/storage` union (it was a
+ * kehto unilateral extension); attempts produce a `storage.clear.result` envelope
+ * with an `error` field set. Internal lifecycle cleanup still uses the
+ * `cleanupNappState()` helper below — it is not napplet-reachable.
  *
  * **Deviation note (Phase 15 to decide):** Set/remove results emit both `ok`
- * (legacy compat) and an `error` field on failure. Canonical `@napplet/nub-storage`
+ * (legacy compat) and an `error` field on failure. Canonical `@napplet/nub/storage`
  * only specifies the optional `error`; napplets check `!result.error` for success.
  * Emitting `ok` preserves backward compatibility with existing in-tree callers.
  * Phase 15 (v1.2 release prep) decides whether to drop `ok` pre-release.
@@ -1207,15 +1207,6 @@ declare function handleStorageNub(windowId: string, msg: NappletMessage, sendToN
  */
 declare function cleanupNappState(pubkey: string, dTag: string, aggregateHash: string, statePersistence: StatePersistence): void;
 
-/**
- * service-dispatch.ts — NIP-5D envelope routing for registered services.
- *
- * Routes NappletMessage envelopes to the correct ServiceHandler based on the
- * message type domain prefix. NUB-domain services (signer.*, relay.*, storage.*)
- * are routed by the domain part of message.type. IFC-routed services (audio,
- * notifications) receive ifc.emit messages and are routed by topic prefix.
- */
-
 /**
  * Route a NappletMessage envelope to the matching service handler.
  *
@@ -1256,4 +1247,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 GuidPersistence, type HashVerifierAdapter, type HotkeyAdapter, type IdentityResolver, type ManifestCache, type ManifestCacheEntry, type ManifestPersistence, type NappKeyEntry, type NappKeyRegistry, type NubEnforceConfig, type PendingUpdate, type PendingUpdateNotifier, RING_BUFFER_SIZE, type RelayConfigAdapter, 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, createManifestCache, createNappKeyRegistry, createNubEnforceGate, createReplayDetector, createRuntime, createSessionRegistry, formatDenialReason, handleStorageNub, matchesAnyFilter, matchesFilter, notifyServiceWindowDestroyed, routeServiceMessage };
+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 GuidPersistence, type HashVerifierAdapter, type HotkeyAdapter, type IdentityResolver, type ManifestCache, type ManifestCacheEntry, type ManifestPersistence, type NappKeyEntry, type NappKeyRegistry, type NappletClass, type NubEnforceConfig, type PendingUpdate, type PendingUpdateNotifier, RING_BUFFER_SIZE, type RelayConfigAdapter, 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, createManifestCache, createNappKeyRegistry, createNubEnforceGate, createReplayDetector, createRuntime, createSessionRegistry, formatDenialReason, handleStorageNub, matchesAnyFilter, matchesFilter, notifyServiceWindowDestroyed, routeServiceMessage };