@kehto/runtime 0.8.0 → 0.11.0

package/README.md

@@ -3,7 +3,7 @@
 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
+> protocol. NAP contracts and runtime APIs are not final; treat this package as
 > current implementation guidance, not as a stable protocol guarantee.
 
 ## Install
@@ -14,7 +14,7 @@ pnpm add @kehto/runtime
 
 ## 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 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 NAP handler, and emits the corresponding reply envelope.
 
 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:
 

package/dist/index.d.ts

@@ -2,9 +2,140 @@ import { NappletMessage, NostrEvent, EventTemplate, NostrFilter } from '@napplet
 export { NappletMessage } from '@napplet/core';
 import { Capability } from '@kehto/acl/capabilities';
 export { ALL_CAPABILITIES, Capability } from '@kehto/acl/capabilities';
+import { Decision, Action, Observation, EvaluateResult, NappletPolicy, RateLimit, ContentMatcher, FirewallConfig } from '@kehto/firewall';
 import { NubMessage } from '@kehto/acl';
 export { NubMessage, resolveCapabilitiesNub } from '@kehto/acl';
 
+/**
+ * Runtime persistence + cache data types.
+ *
+ * Host-implemented persistence adapters (ACL, firewall, manifest, shell-secret,
+ * GUID, napplet state) plus the cached-entry shapes they store. Extracted from
+ * types.ts to keep that file under the size budget; re-exported from types.ts so
+ * the public @kehto/runtime API is unchanged.
+ */
+
+/**
+ * ACL persistence — runtime calls these to save/load ACL state.
+ * Implementor decides storage backend (localStorage, file, DB, etc.).
+ */
+interface AclPersistence {
+    persist(data: string): void;
+    load(): string | null;
+}
+/**
+ * Firewall persistence — runtime calls these to save/load firewall config.
+ * Implementor decides storage backend (localStorage, file, DB, etc.).
+ * Only the firewall config is persisted; ephemeral counters are never stored.
+ *
+ * @param persist - Store serialized config data; called after each policy mutation.
+ * @param load    - Retrieve previously stored config, or null on first boot.
+ */
+interface FirewallPersistence {
+    persist(data: string): void;
+    load(): string | null;
+}
+/**
+ * Event emitted on every firewall evaluation that results in an audit-level
+ * decision (flag, block, or prompt).
+ *
+ * @param windowId        - The napplet window that sent the message.
+ * @param napplet         - The napplet dTag (version-agnostic identity key).
+ * @param opClass         - Operation class string (e.g. 'relay:write', 'outbox:publish').
+ * @param decision        - Primary disposition: 'pass', 'reject', or 'prompt'.
+ * @param action          - The matched rule's exceed-action: 'flag', 'block', or 'ignore'.
+ * @param ruleId          - Identifier of the rule that made the decision.
+ * @param reason          - Human-readable reason string for logging/audit.
+ * @param message         - The triggering NappletMessage, if available.
+ */
+interface FirewallEvent {
+    /** The napplet window that sent the message. */
+    windowId: string;
+    /** The napplet dTag (version-agnostic identity key). */
+    napplet: string;
+    /** Operation class string (e.g. 'relay:write', 'outbox:publish', 'intent:invoke'). */
+    opClass: string;
+    /** Primary disposition for the caller. */
+    decision: Decision;
+    /** The matched rule's exceed-action. */
+    action: Action;
+    /** Identifier of the rule that made the decision (e.g. 'rate:default', 'burst', 'policy:deny'). */
+    ruleId: string;
+    /** Human-readable reason string for logging and audit. */
+    reason: string;
+    /** The triggering message, if available. */
+    message?: NappletMessage;
+}
+/**
+ * Manifest persistence — runtime calls these to save/load manifest cache.
+ * Implementor decides storage backend.
+ */
+interface ManifestPersistence {
+    persist(data: string): void;
+    load(): string | null;
+}
+/**
+ * Shell secret persistence — runtime calls these to save/load the per-shell secret
+ * used for deterministic keypair derivation. The secret is a 32-byte random value
+ * generated once on first use.
+ */
+interface ShellSecretPersistence {
+    /** Get the stored shell secret, or null if not yet generated. */
+    get(): Uint8Array | null;
+    /** Store the shell secret. */
+    set(secret: Uint8Array): void;
+}
+/**
+ * GUID persistence — runtime calls these to save/load per-iframe instance GUIDs.
+ * GUIDs survive page reloads: same iframe slot gets the same GUID.
+ * Implementor decides storage backend and keying strategy
+ * (e.g., localStorage keyed by iframe src or slot index).
+ */
+interface GuidPersistence {
+    /** Get a stored GUID for a window identifier, or null if none exists. */
+    get(windowId: string): string | null;
+    /** Store a GUID for a window identifier. */
+    set(windowId: string, guid: string): void;
+    /** Remove a stored GUID. */
+    remove(windowId: string): void;
+}
+/**
+ * State storage — runtime calls these for napplet-scoped key-value storage.
+ * All keys are pre-scoped by the runtime (dTag:hash:userKey).
+ */
+interface StatePersistence {
+    get(scopedKey: string): string | null;
+    set(scopedKey: string, value: string): boolean;
+    remove(scopedKey: string): void;
+    clear(prefix: string): void;
+    keys(prefix: string): string[];
+    calculateBytes(prefix: string, excludeKey?: string): number;
+}
+/**
+ * A cached manifest entry for a verified napplet build.
+ * Optionally stores the napplet's declared service requirements from its manifest.
+ */
+interface ManifestCacheEntry {
+    pubkey: string;
+    dTag: string;
+    aggregateHash: string;
+    verifiedAt: number;
+    /** Service names declared in the napplet's manifest requires tags. */
+    requires?: string[];
+}
+/**
+ * Cached verification result for an aggregate hash.
+ * Keyed by manifest event ID — immutable Nostr events mean same ID = same content.
+ */
+interface VerificationCacheEntry {
+    /** The computed aggregate hash. */
+    aggregateHash: string;
+    /** Whether the computed hash matched the declared hash. */
+    valid: boolean;
+    /** Timestamp when verification was performed. */
+    verifiedAt: number;
+}
+
 /**
  * types.ts — Runtime adapter interfaces and supporting types.
  *
@@ -15,7 +146,7 @@ export { NubMessage, resolveCapabilitiesNub } from '@kehto/acl';
 /**
  * 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
+ * converges on @napplet/nap/class@^0.3.0 publish. Runtime MUST NOT import
  * from shell (module-boundary), so this duplicate lives here.
  */
 type NappletClass = string | null;
@@ -151,59 +282,7 @@ interface HotkeyAdapter {
         metaKey: boolean;
     }): void;
 }
-/**
- * ACL persistence — runtime calls these to save/load ACL state.
- * Implementor decides storage backend (localStorage, file, DB, etc.).
- */
-interface AclPersistence {
-    persist(data: string): void;
-    load(): string | null;
-}
-/**
- * Manifest persistence — runtime calls these to save/load manifest cache.
- * Implementor decides storage backend.
- */
-interface ManifestPersistence {
-    persist(data: string): void;
-    load(): string | null;
-}
-/**
- * Shell secret persistence — runtime calls these to save/load the per-shell secret
- * used for deterministic keypair derivation. The secret is a 32-byte random value
- * generated once on first use.
- */
-interface ShellSecretPersistence {
-    /** Get the stored shell secret, or null if not yet generated. */
-    get(): Uint8Array | null;
-    /** Store the shell secret. */
-    set(secret: Uint8Array): void;
-}
-/**
- * GUID persistence — runtime calls these to save/load per-iframe instance GUIDs.
- * GUIDs survive page reloads: same iframe slot gets the same GUID.
- * Implementor decides storage backend and keying strategy
- * (e.g., localStorage keyed by iframe src or slot index).
- */
-interface GuidPersistence {
-    /** Get a stored GUID for a window identifier, or null if none exists. */
-    get(windowId: string): string | null;
-    /** Store a GUID for a window identifier. */
-    set(windowId: string, guid: string): void;
-    /** Remove a stored GUID. */
-    remove(windowId: string): void;
-}
-/**
- * State storage — runtime calls these for napplet-scoped key-value storage.
- * All keys are pre-scoped by the runtime (dTag:hash:userKey).
- */
-interface StatePersistence {
-    get(scopedKey: string): string | null;
-    set(scopedKey: string, value: string): boolean;
-    remove(scopedKey: string): void;
-    clear(prefix: string): void;
-    keys(prefix: string): string[];
-    calculateBytes(prefix: string, excludeKey?: string): number;
-}
+
 /** Crypto adapter — event verification. */
 interface CryptoAdapter {
     /** Verify a nostr event's Schnorr signature. */
@@ -260,8 +339,8 @@ interface DmAdapter {
     }>;
 }
 /**
- * A pending consent request — either for a destructive signing kind
- * or for undeclared service usage.
+ * A pending consent request — for a destructive signing kind, undeclared
+ * service usage, or a firewall policy prompt.
  *
  * When type is 'destructive-signing' (or omitted for backwards compat):
  *   Raised when a signer request arrives for kinds 0, 3, 5, 10002.
@@ -270,6 +349,15 @@ interface DmAdapter {
  *   Raised when a napplet uses a service it did not declare in its manifest.
  *   The serviceName field identifies which service was used without declaration.
  *
+ * When type is 'firewall-policy':
+ *   Raised when the firewall evaluation returns a 'prompt' decision (ask policy).
+ *   No Nostr event is associated — `event` is omitted. The `napplet` field
+ *   carries the dTag the user's allow/deny choice will be remembered against.
+ *   The triggering message is rejected now; if the user allows, subsequent
+ *   messages from this napplet will pass without re-prompting (choice persisted
+ *   as a per-napplet policy via setPolicy). Phase 82 changeset note: `event`
+ *   was relaxed from required to optional to accommodate this variant (A3).
+ *
  * @example
  * ```ts
  * // Destructive signing consent (existing behavior)
@@ -279,24 +367,41 @@ interface DmAdapter {
  *   resolve: (allowed) => { ... },
  * };
  *
- * // Undeclared service consent (new)
+ * // Undeclared service consent
  * const serviceConsent: ConsentRequest = {
  *   type: 'undeclared-service',
  *   windowId: 'win-1', pubkey: 'abc...', event: serviceEvent,
  *   serviceName: 'audio',
  *   resolve: (allowed) => { ... },
  * };
+ *
+ * // Firewall policy prompt (no Nostr event)
+ * const firewallConsent: ConsentRequest = {
+ *   type: 'firewall-policy',
+ *   windowId: 'win-1', pubkey: 'abc...', napplet: 'chat',
+ *   resolve: (allowed) => { ... },
+ * };
  * ```
  */
 interface ConsentRequest {
     /** Consent type discriminator. Defaults to 'destructive-signing' if omitted. */
-    type?: 'destructive-signing' | 'undeclared-service';
+    type?: 'destructive-signing' | 'undeclared-service' | 'firewall-policy';
     windowId: string;
     pubkey: string;
-    event: NostrEvent;
+    /**
+     * The Nostr event associated with this consent request.
+     * Optional for 'firewall-policy' consent — a firewall prompt has no real Nostr event.
+     * Present for 'destructive-signing' and 'undeclared-service' requests.
+     */
+    event?: NostrEvent;
     resolve: (allowed: boolean) => void;
     /** Service name for undeclared-service consent. Only present when type is 'undeclared-service'. */
     serviceName?: string;
+    /**
+     * The napplet dTag the firewall policy choice is remembered against.
+     * Only present when type is 'firewall-policy'.
+     */
+    napplet?: string;
 }
 /** Consent handler callback type. */
 type ConsentHandler = (request: ConsentRequest) => void;
@@ -418,30 +523,6 @@ interface PendingUpdate {
 }
 /** Callback invoked when a pending update is set or cleared. */
 type PendingUpdateNotifier = (windowId: string) => void;
-/**
- * A cached manifest entry for a verified napplet build.
- * Optionally stores the napplet's declared service requirements from its manifest.
- */
-interface ManifestCacheEntry {
-    pubkey: string;
-    dTag: string;
-    aggregateHash: string;
-    verifiedAt: number;
-    /** Service names declared in the napplet's manifest requires tags. */
-    requires?: string[];
-}
-/**
- * Cached verification result for an aggregate hash.
- * Keyed by manifest event ID — immutable Nostr events mean same ID = same content.
- */
-interface VerificationCacheEntry {
-    /** The computed aggregate hash. */
-    aggregateHash: string;
-    /** Whether the computed hash matched the declared hash. */
-    valid: boolean;
-    /** Timestamp when verification was performed. */
-    verifiedAt: number;
-}
 /** External ACL entry — used in shell commands (shell:acl-get etc.). */
 interface AclEntryExternal {
     pubkey: string;
@@ -610,6 +691,30 @@ interface RuntimeAdapter {
     onHashMismatch?: (dTag: string, claimed: string, computed: string) => void;
     /** Called on every ACL enforcement check (audit). */
     onAclCheck?: (event: AclCheckEvent) => void;
+    /**
+     * Firewall config persistence (save/load firewall config).
+     * When absent, firewall config is in-memory only and resets on reload.
+     * Only the config is persisted; ephemeral counters are never stored.
+     */
+    firewallPersistence?: FirewallPersistence;
+    /**
+     * Called on every firewall evaluation that results in an audit-level decision
+     * (flag, block, or prompt). When absent, firewall decisions are not audited.
+     */
+    onFirewallEvent?: (event: FirewallEvent) => void;
+    /**
+     * Returns the current focus state for a napplet window.
+     * When absent, defaults to `{ focused: true }` — a host without a window
+     * manager treats everything as focused, so focus never tightens rate budgets.
+     * Focus alone never hard-blocks; it only scales token refill rates.
+     *
+     * @param windowId - The napplet window to query focus state for.
+     * @returns Current focus state and optional milliseconds since last focus gain.
+     */
+    getFocusContext?: (windowId: string) => {
+        focused: boolean;
+        msSinceFocusGain?: number;
+    };
     /** Called when a pending napp update is set or cleared. */
     onPendingUpdate?: PendingUpdateNotifier;
     /**
@@ -876,6 +981,102 @@ interface AclStateContainer {
  */
 declare function createAclState(persistence: AclPersistence, defaultPolicy?: 'permissive' | 'restrictive'): AclStateContainer;
 
+/**
+ * firewall-state.ts — Firewall state container with persistence hooks.
+ *
+ * Wraps @kehto/firewall's pure functions with persistence via
+ * FirewallPersistence. No localStorage or DOM references.
+ *
+ * Two independent `let`-bound cells:
+ *   - `config`   — immutable FirewallConfig; persisted on each mutation.
+ *   - `counters` — ephemeral FirewallState (token-buckets + burst counters);
+ *                  in-memory only, reset on reload (RUNTIME-03).
+ *
+ * CRITICAL: `evaluate` reassigns `counters = result.newState` on every call.
+ * Without this, token buckets never advance and flood events never escalate
+ * from 'flag' to 'block'.
+ */
+
+/**
+ * Stateful firewall container — wraps @kehto/firewall's pure functions
+ * with persistence and a convenient imperative API.
+ *
+ * Mirrors AclStateContainer from acl-state.ts in structure and naming.
+ *
+ * @example
+ * ```ts
+ * const firewall = createFirewallState(persistence);
+ * firewall.load();
+ * const result = firewall.evaluate({ napplet: 'chat', opClass: 'relay:write', focused: true, now: Date.now() });
+ * ```
+ */
+interface FirewallStateContainer {
+    /**
+     * Evaluate an observation against the current firewall config and counters.
+     * CRITICAL: advances the in-memory counter state on each call.
+     *
+     * @param observation - Normalized observation extracted from the napplet message envelope.
+     * @returns The full EvaluateResult (decision, action, ruleId, reason, newState).
+     */
+    evaluate(observation: Observation): EvaluateResult;
+    /**
+     * Set a per-napplet policy override (allow / deny / ask).
+     *
+     * @param napplet - The napplet dTag (version-agnostic identity key).
+     * @param policy  - Hard policy override for this napplet.
+     */
+    setPolicy(napplet: string, policy: NappletPolicy): void;
+    /**
+     * Set a per-(napplet, opClass) token-bucket rate limit.
+     *
+     * @param napplet  - The napplet dTag.
+     * @param opClass  - The operation class string.
+     * @param limit    - The rate limit to apply.
+     */
+    setRateLimit(napplet: string, opClass: string, limit: RateLimit): void;
+    /**
+     * Set a global rate limit applied to all op-classes that have no specific entry.
+     *
+     * @param napplet - The napplet dTag.
+     * @param limit   - The global fallback rate limit.
+     */
+    setGlobalRate(napplet: string, limit: RateLimit): void;
+    /**
+     * Add a content matcher to the firewall config.
+     *
+     * @param matcher - The content matcher to append.
+     */
+    addMatcher(matcher: ContentMatcher): void;
+    /** Return the current firewall config. */
+    getConfig(): FirewallConfig;
+    /** Persist the current firewall config via the persistence hook. Best-effort. */
+    persist(): void;
+    /** Load previously persisted firewall config. Counters are NOT restored. */
+    load(): void;
+    /** Reset config to defaultConfig() and counters to createState(), then persist empty. */
+    clear(): void;
+}
+/**
+ * Create a firewall state container backed by @kehto/firewall and optionally
+ * persisted via the given persistence hooks.
+ *
+ * When `persistence` is absent (or undefined), firewall config is in-memory
+ * only and resets on container recreation. This is safe for hosts that do not
+ * need durable per-napplet policies.
+ *
+ * @param persistence - Optional storage backend for firewall config.
+ * @returns A FirewallStateContainer instance.
+ *
+ * @example
+ * ```ts
+ * const firewall = createFirewallState(persistence);
+ * firewall.load();
+ * firewall.setPolicy('chat', 'allow');
+ * firewall.persist();
+ * ```
+ */
+declare function createFirewallState(persistence?: FirewallPersistence): FirewallStateContainer;
+
 /**
  * manifest-cache.ts — Manifest cache with persistence hooks.
  *
@@ -1127,6 +1328,8 @@ interface Runtime {
     readonly sessionRegistry: SessionRegistry;
     /** Access the ACL state container. */
     readonly aclState: AclStateContainer;
+    /** Access the firewall state container (for tests to pre-set policy/rules). */
+    readonly firewallState: FirewallStateContainer;
     /** Access the manifest cache. */
     readonly manifestCache: ManifestCache;
 }
@@ -1149,25 +1352,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/nap/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/nap/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
+ * `storage.clear` is NOT in the canonical `@napplet/nap/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/nap/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.
@@ -1247,4 +1450,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 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 };
+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 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, createFirewallState, createManifestCache, createNappKeyRegistry, createNubEnforceGate, createReplayDetector, createRuntime, createSessionRegistry, formatDenialReason, handleStorageNub, matchesAnyFilter, matchesFilter, notifyServiceWindowDestroyed, routeServiceMessage };