@kehto/services 0.7.0 → 0.9.1

package/README.md

@@ -154,7 +154,7 @@ runtime.registerService('keys', createKeysService({ hostBridge: electronBridge }
 
 Plug a `HostKeysBridge` when the default document listener is insufficient: Electron or Tauri apps that need to register OS-level global hotkeys (chords delivered even when the host window is not focused), native shells that route chords through a platform-specific hotkey manager (macOS Carbon, Linux X11 grab, Windows RegisterHotKey), or test harnesses that inject synthetic events through a controlled `EventTarget`. The bridge owns subscription lifecycle; the service retains per-window bookkeeping (so `onWindowDestroyed` cleanup stays identical across paths).
 
-See the demo: [`apps/playground/napplets/hotkey-chord/src/main.ts`](../../apps/playground/napplets/hotkey-chord/src/main.ts) (the Phase 26 end-to-end exemplar — uses `@napplet/sdk` `keys.registerAction` + `keys.onAction` against the real backend).
+A napplet drives this end to end via `@napplet/sdk` — `keys.registerAction` to claim a chord and `keys.onAction` to receive dispatches against the real backend.
 
 ### Reserved Chords
 
@@ -344,7 +344,7 @@ runtime.registerService('media', createMediaService({ hostBridge: electronBridge
 
 Plug a `HostMediaBridge` when `navigator.mediaSession` is insufficient: Electron apps that need to route transport events through the main process (lock-screen integration on Windows, Now Playing integration on macOS), Linux shells that speak MPRIS over D-Bus, native mobile wrappers that forward to AVPlayer / ExoPlayer, or test harnesses that record action events without touching the DOM. The bridge owns metadata/state mirroring and OS action routing; the service retains per-session bookkeeping (sessionRegistry + per-window send handles) so `media.command` dispatch semantics stay identical across paths.
 
-See the demo: [`apps/playground/napplets/media-controller/src/main.ts`](../../apps/playground/napplets/media-controller/src/main.ts) (the Phase 27 end-to-end exemplar — uses `@napplet/nub/media` `mediaCreateSession({ owner: 'napplet', ... })` + `mediaReportState` + `mediaOnCommand` against the real backend).
+A napplet drives this end to end via `@napplet/nub/media` — `mediaCreateSession({ owner: 'napplet', ... })`, `mediaReportState`, and `mediaOnCommand` against the real backend.
 
 ## Public API
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
-import { NostrEvent, NappletMessage, NostrFilter, EventTemplate } from '@napplet/core';
+import { NostrFilter, NostrEvent, EventTemplate } from '@napplet/core';
 import { MediaMetadata, MediaAction } from '@napplet/nub/media/types';
 export { MediaAction } from '@napplet/nub/media/types';
 import { NotifySendMessage } from '@napplet/nub/notify/types';
@@ -181,53 +181,19 @@ declare function createNotificationService(options?: NotificationServiceOptions)
  *   - signer.nip04.encrypt/decrypt -> DELETED
  *   - signer.nip44.encrypt/decrypt -> DELETED (shell encrypts internally
  *                                      inside relay.publishEncrypted)
- *   - identity.decrypt -> ADDED in v1.8 as a shell-mediated decrypt request
- *                         with class gate + typed error union.
  *
- * See REQUIREMENTS.md DEPS-03 (Phase 15 changelog).
+ * Identity is strictly read-only per NAP-IDENTITY: napplets learn *about* the
+ * user but cannot act *as* the user — no signing, encryption, or decryption.
+ * (An `identity.decrypt` capability was briefly added in v1.8 and removed as a
+ * spec violation; decryption belongs to the runtime, inline over the wire.)
  *
- * Handles 10 identity.* request types from @napplet/nub/identity. getPublicKey
+ * Handles 9 identity.* request types from @napplet/nub/identity. getPublicKey
  * and getRelays return real values sourced from hooks.auth.getSigner(); the
  * remaining 7 (getProfile/getFollows/getList/getZaps/getMutes/getBlocked/
- * getBadges) are stub-level; decrypt delegates to a host-supplied bridge.
- * Host apps plug real backends via runtime.registerService('identity', realHandler).
+ * getBadges) are stub-level. Host apps plug real backends via
+ * runtime.registerService('identity', realHandler).
  */
 
-type IdentityDecryptErrorCode = 'class-forbidden' | 'signer-denied' | 'signer-unavailable' | 'decrypt-failed' | 'malformed-wrap' | 'impersonation' | 'unsupported-encryption' | 'policy-denied';
-interface Rumor {
-    id: string;
-    pubkey: string;
-    created_at: number;
-    kind: number;
-    tags: string[][];
-    content: string;
-}
-interface IdentityDecryptMessage extends NappletMessage {
-    type: 'identity.decrypt';
-    id: string;
-    event: NostrEvent;
-}
-interface IdentityDecryptResultMessage extends NappletMessage {
-    type: 'identity.decrypt.result';
-    id: string;
-    rumor: Rumor;
-    sender: string;
-}
-interface IdentityDecryptErrorMessage extends NappletMessage {
-    type: 'identity.decrypt.error';
-    id: string;
-    error: IdentityDecryptErrorCode;
-}
-interface GiftWrapDecryptResult {
-    seal: NostrEvent;
-    rumor: Rumor;
-}
-interface HostDecryptBridge {
-    nip04Decrypt(senderPubkey: string, ciphertext: string): Promise<string>;
-    nip44Decrypt(senderPubkey: string, ciphertext: string): Promise<string>;
-    unwrapGiftWrap(wrap: NostrEvent): Promise<GiftWrapDecryptResult>;
-}
-type VerifyEvent = (event: NostrEvent) => boolean | Promise<boolean>;
 /**
  * Options for creating the identity service.
  *
@@ -246,27 +212,14 @@ interface IdentityServiceOptions {
      * availability can change dynamically.
      */
     getSigner: () => Signer | null;
-    /**
-     * Return the host decrypt bridge. Called only after outer event signature
-     * verification and encryption-mode detection succeed. Null means decrypt is
-     * unavailable while the rest of the identity service remains usable.
-     */
-    getDecryptor?: () => HostDecryptBridge | null;
-    /**
-     * Verify a received event before any decrypt attempt. Host shells should
-     * wire this to their canonical Nostr event verifier; tests and old hosts
-     * default to true for backward compatibility with the 9 read-only actions.
-     */
-    verifyEvent?: VerifyEvent;
 }
 /**
  * Create an identity service that handles NIP-5D identity.* envelope messages.
  *
- * Supports all 10 identity.* request types from @napplet/nub/identity. The two
- * read-only nostr-info queries (getPublicKey, getRelays) resolve through the
+ * Supports the 9 read-only identity.* request types from @napplet/nub/identity.
+ * The two nostr-info queries (getPublicKey, getRelays) resolve through the
  * caller-supplied signer; the remaining 7 return default/empty payloads with
  * spec-correct envelope shapes so napplets always receive a result envelope.
- * identity.decrypt delegates to the host decrypt bridge.
  *
  * @param options - Identity service configuration (getSigner)
  * @returns A ServiceHandler ready for runtime.registerService('identity', handler)
@@ -2028,4 +1981,300 @@ interface HttpUploaderOptions {
  */
 declare function createHttpUploader(options: HttpUploaderOptions): Uploader;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type GiftWrapDecryptResult, type HostCacheBridge, type HostDecryptBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityDecryptErrorCode, type IdentityDecryptErrorMessage, type IdentityDecryptMessage, type IdentityDecryptResultMessage, type IdentityServiceOptions, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type Rumor, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type VerifyEvent, createAudioService, createBrowserMediaBridge, createCacheService, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService };
+/**
+ * intent-types.ts — NAP-INTENT (archetype intent dispatch) value types.
+ *
+ * Kehto-internal model for the NAP-INTENT wire contract (upstream draft:
+ * napplet/nubs NAP-INTENT, namespace `window.napplet.intent`). The installed
+ * `@napplet/core` peer predates these types, so — as with {@link ./cvm-types} —
+ * kehto defines them here, wire-compatible with the upstream shapes, rather
+ * than redefining the generic NIP-5D envelope.
+ *
+ * NAP-INTENT standardizes the *envelope*, not the payload. `archetype` is the
+ * routing axis (which role, whose default), `protocol` is the parsing axis
+ * (which NAP-N wire format shapes `payload`); the two are orthogonal.
+ *
+ * @packageDocumentation
+ */
+/**
+ * How the shell should pick the handling napplet for an intent.
+ *
+ * - `"default"` — route to the user's default handler for the archetype.
+ * - `"choose"`  — prompt the user with an "open with…" chooser.
+ * - any other string — a specific napplet dTag (cross-napplet targeting; the
+ *   shell SHOULD require the user to have authorized this for the caller).
+ */
+type IntentHandlerPreference = 'default' | 'choose' | (string & {});
+/** Window-behavior hints carried with an intent invoke. */
+interface IntentBehavior {
+    /** Bring the handler window to the foreground. */
+    focus?: boolean;
+    /** Force a new window rather than reusing an existing handler instance. */
+    newWindow?: boolean;
+    /** Prefer reusing an already-open handler instance when one exists. */
+    reuse?: boolean;
+}
+/** A request to dispatch an action to a napplet of a given archetype. */
+interface IntentRequest {
+    /** Role slug, e.g. `"note"` (see the archetype registry). */
+    archetype: string;
+    /** Verb, default `"open"` (e.g. `"open"` | `"edit"` | `"pick"` | `"share"`). */
+    action?: string;
+    /** NAP-N id shaping `payload`; omit to use the archetype's recommended default. */
+    protocol?: string;
+    /** Opaque payload, typed by `protocol`. */
+    payload?: unknown;
+    /** Handler-selection preference. */
+    handler?: IntentHandlerPreference;
+    /** Window-behavior hints. */
+    behavior?: IntentBehavior;
+}
+/** A napplet that can fulfill an archetype, sourced from the manifest catalog. */
+interface IntentCandidate {
+    /** dTag of the napplet that can fulfill the archetype. */
+    dTag: string;
+    /** Human-readable title from the manifest. */
+    title?: string;
+    /** Verbs this candidate supports for the archetype. */
+    actions: string[];
+    /** NAP-N ids this candidate accepts for the archetype. */
+    protocols: string[];
+    /** Whether this candidate is the user/runtime default for the archetype. */
+    isDefault?: boolean;
+}
+/** Availability of an archetype, sourced from the installed-napplet catalog. */
+interface IntentAvailability {
+    /** The archetype this availability describes. */
+    archetype: string;
+    /** True when at least one installed napplet fulfills the archetype. */
+    available: boolean;
+    /** Candidate napplets that fulfill the archetype (from manifests, not instances). */
+    candidates: IntentCandidate[];
+    /** True when a user/runtime default handler is set for the archetype. */
+    hasDefault: boolean;
+}
+/** The result of an intent invocation. */
+interface IntentResult {
+    /** Whether the intent was dispatched successfully. */
+    ok: boolean;
+    /** The requested archetype, echoed back. */
+    archetype: string;
+    /** The resolved action (defaults to `"open"` when the request omits it). */
+    action: string;
+    /** True when a handler accepted the dispatch. */
+    handled: boolean;
+    /** dTag of the napplet that handled the intent, when one did. */
+    handler?: string;
+    /** Window id the handler was created or focused in. */
+    windowId?: string;
+    /** The wire format actually used to deliver `payload`. */
+    protocol?: string;
+    /** Error reason when the intent could not be fulfilled. */
+    error?: string;
+}
+
+/**
+ * intent-service.ts — NAP-INTENT (archetype intent dispatch) reference service.
+ *
+ * Shell-side handler for the NAP-INTENT wire protocol. It is a pure envelope
+ * router: it validates `intent.*` envelopes, delegates archetype resolution,
+ * default handling, window lifecycle, and payload delivery to an injected
+ * {@link IntentResolver}, and posts the correlated result / push messages
+ * (echoing the request `id`) back to the napplet.
+ *
+ * The resolver is injected (options-as-bridge) so this service has no shell or
+ * window-manager dependency and is fully unit-testable. A concrete
+ * catalog-backed resolver ships alongside as {@link createCatalogIntentResolver}.
+ *
+ * ──────────────────────────── Responsibilities ────────────────────────────
+ *   Inbound:  intent.invoke, intent.available, intent.handlers
+ *   Outbound: intent.invoke.result, intent.available.result,
+ *             intent.handlers.result, intent.changed
+ *
+ * The shell owns archetype→handler resolution, the user's default-handler
+ * preference, the "open with…" chooser, and window creation/focus — all behind
+ * the {@link IntentResolver}. This service only marshals the wire protocol and
+ * fans `intent.changed` pushes out to the napplets it has served.
+ *
+ * @example
+ * ```ts
+ * import { createIntentService, createCatalogIntentResolver } from '@kehto/services';
+ *
+ * const resolver = createCatalogIntentResolver({ loadCatalog, windows });
+ * runtime.registerService('intent', createIntentService({ resolver }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Context passed to {@link IntentResolver.invoke} for trust/attribution. */
+interface IntentResolverContext {
+    /** Window id of the napplet that issued the request. */
+    windowId: string;
+}
+/**
+ * Abstract intent resolver. Implementors own the installed-napplet catalog,
+ * archetype→handler resolution, the user's default-handler preference, the
+ * "open with…" chooser, window creation/focus, and payload delivery. The
+ * service translates wire envelopes into these calls and back.
+ */
+interface IntentResolver {
+    /**
+     * Resolve `request.archetype` to a handler, create or focus its window, and
+     * deliver `payload`. Returns once the handler is resolved and the window
+     * created; delivery MAY complete asynchronously.
+     */
+    invoke(request: IntentRequest, context: IntentResolverContext): IntentResult | Promise<IntentResult>;
+    /** Report whether the runtime can currently satisfy `archetype`, and how. */
+    available(archetype: string): IntentAvailability | Promise<IntentAvailability>;
+    /** Report availability for every archetype the runtime can currently satisfy. */
+    handlers(): IntentAvailability[] | Promise<IntentAvailability[]>;
+    /**
+     * Register for availability changes (a napplet installed/removed, or a default
+     * handler changed). The service forwards each change to served napplets as an
+     * `intent.changed` push. Returns an unsubscribe handle. Resolvers whose
+     * catalog never changes at runtime MAY omit this.
+     */
+    onChanged?(listener: (availability: IntentAvailability) => void): () => void;
+}
+/** Options for {@link createIntentService}. */
+interface IntentServiceOptions {
+    /** The intent resolver the shell uses to route archetypes. Required. */
+    resolver: IntentResolver;
+}
+/**
+ * Create the NAP-INTENT service handler.
+ *
+ * @param options - Must provide an {@link IntentResolver}.
+ * @returns A `ServiceHandler` ready for `runtime.registerService('intent', handler)`.
+ * @throws If `options.resolver` is missing.
+ */
+declare function createIntentService(options: IntentServiceOptions): ServiceHandler;
+
+/**
+ * catalog-intent-resolver.ts — NAP-INTENT concrete {@link IntentResolver}.
+ *
+ * A reference resolver that satisfies {@link IntentResolver} from an
+ * installed-napplet catalog plus host-supplied policy: the user's
+ * default-handler preference, an optional "open with…" chooser, the archetype's
+ * recommended default protocol, and a window controller that creates or focuses
+ * the handler window and delivers the payload.
+ *
+ * Resolution policy (mirrors an OS implicit-intent + default-app model):
+ *   1. Gather candidates for the archetype from the catalog.
+ *   2. Pick the handler — an explicit `handler` dTag, a user choice
+ *      (`handler: "choose"`), the user's default, the sole candidate, or a
+ *      deterministic first-candidate fallback.
+ *   3. Validate the resolved handler supports the requested `action` and
+ *      `protocol` (or fall back to the archetype's recommended default protocol,
+ *      then the candidate's first accepted protocol).
+ *   4. Open or focus the handler window and return its id.
+ *
+ * The catalog, defaults, chooser, and window controller are all injected, so
+ * this resolver carries no shell, manifest, or DOM dependency and is fully
+ * unit-testable.
+ *
+ * @packageDocumentation
+ */
+
+/** The actions/protocols a napplet fulfills for a single archetype. */
+interface IntentArchetypeSupport {
+    /** Verbs this napplet supports for the archetype (e.g. `["open", "edit"]`). */
+    actions: string[];
+    /** NAP-N protocol ids this napplet accepts for the archetype. */
+    protocols: string[];
+}
+/**
+ * One installed napplet's intent surface, derived from its signed NIP-5A
+ * manifest. Keyed by archetype slug so a single napplet can fulfill several
+ * roles.
+ */
+interface IntentCatalogEntry {
+    /** The napplet's dTag. */
+    dTag: string;
+    /** Human-readable title from the manifest. */
+    title?: string;
+    /** Archetype slug → the actions/protocols this napplet fulfills for it. */
+    archetypes: Record<string, IntentArchetypeSupport>;
+}
+/** Parameters handed to {@link IntentWindowController.open}. */
+interface IntentOpenParams {
+    /** dTag of the resolved handler napplet. */
+    dTag: string;
+    /** The archetype being dispatched. */
+    archetype: string;
+    /** The resolved action (e.g. `"open"`). */
+    action: string;
+    /** The wire format the payload is delivered with, when one was resolved. */
+    protocol?: string;
+    /** The opaque payload to deliver. */
+    payload?: unknown;
+    /** Window-behavior hints from the request. */
+    behavior?: IntentBehavior;
+    /** Window id of the napplet that issued the intent. */
+    callerWindowId: string;
+}
+/** Creates or focuses the handler window and delivers the intent payload. */
+interface IntentWindowController {
+    /**
+     * Create or focus the handler window and deliver `payload` via `protocol`.
+     * Returns the window id the handler was created or focused in.
+     */
+    open(params: IntentOpenParams): {
+        windowId: string;
+    } | Promise<{
+        windowId: string;
+    }>;
+}
+/** Options for {@link createCatalogIntentResolver}. */
+interface CatalogIntentResolverOptions {
+    /** Return the installed-napplet catalog (signed NIP-5A manifests). Required. */
+    loadCatalog(): IntentCatalogEntry[] | Promise<IntentCatalogEntry[]>;
+    /** Window controller used to create/focus the resolved handler's window. Required. */
+    windows: IntentWindowController;
+    /**
+     * The user's default handler dTag for an archetype, or `undefined` when none
+     * is set. Default-handler settings are user state — never set by napplets.
+     */
+    getDefaultHandler?(archetype: string): string | undefined;
+    /**
+     * Resolve a `handler: "choose"` prompt (or a no-default ambiguity) to a dTag.
+     * Returning `undefined` means the user cancelled. When omitted, ambiguous
+     * resolution falls back to the first candidate.
+     */
+    chooseHandler?(archetype: string, candidates: IntentCandidate[], callerWindowId: string): string | undefined | Promise<string | undefined>;
+    /** The archetype's recommended default protocol when the caller omits one. */
+    defaultProtocol?(archetype: string): string | undefined;
+}
+/**
+ * A {@link IntentResolver} backed by a catalog, with a host hook to announce
+ * catalog/default changes.
+ */
+interface CatalogIntentResolver extends IntentResolver {
+    /**
+     * Announce that the catalog or default handler for `archetype` changed. The
+     * resolver recomputes availability and notifies `onChanged` listeners, which
+     * the intent service forwards to napplets as `intent.changed` pushes.
+     */
+    notifyChanged(archetype: string): void;
+}
+/**
+ * Create a catalog-backed NAP-INTENT resolver.
+ *
+ * @param options - Catalog loader and window controller (required) plus
+ *   optional default-handler, chooser, and default-protocol policy hooks.
+ * @returns A {@link CatalogIntentResolver} for `createIntentService({ resolver })`.
+ * @throws If `options.loadCatalog` or `options.windows` is missing.
+ *
+ * @example
+ * ```ts
+ * const resolver = createCatalogIntentResolver({
+ *   loadCatalog: () => installedNapplets,
+ *   windows: { open: ({ dTag }) => ({ windowId: openWindow(dTag) }) },
+ *   getDefaultHandler: (a) => userDefaults[a],
+ * });
+ * ```
+ */
+declare function createCatalogIntentResolver(options: CatalogIntentResolverOptions): CatalogIntentResolver;
+
+export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentAvailability, type IntentBehavior, type IntentCandidate, type IntentCatalogEntry, type IntentHandlerPreference, type IntentOpenParams, type IntentRequest, type IntentResolver, type IntentResolverContext, type IntentResult, type IntentServiceOptions, type IntentWindowController, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, createAudioService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createIntentService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService };