@kehto/services 0.20.1 → 0.21.1

package/README.md

@@ -17,7 +17,7 @@ pnpm add @kehto/services
 ## Published Napplet Compatibility
 
 `@kehto/services` publishes against `@napplet/core` and `@napplet/nap`
-`>=0.31.0 <0.32.0`. The exact installed contracts are core 0.31.1 / nap 0.31.2
+`>=0.32.0 <0.33.0`. The exact installed contracts are core 0.32.0 / nap 0.32.0
 from NAP-INTENT authority `5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`,
 napplet/web#199 source `3037200c932488f14f7f369b8583c39c9c16510a` / merge
 `b3f0007867eac109fa4917fac9c285d3b7cc6155`, and Version Packages #198 release
@@ -43,8 +43,8 @@ Current draft posture:
 - `createKeysService` and `createMediaService` ship real reference backends as of v1.4 (see the dedicated sections below). `createKeysService` attaches a document-level `keydown` listener by default and delivers `keys.action` push envelopes to registered napplets; `createMediaService` mirrors session metadata and playback state to `navigator.mediaSession` and emits `media.command` push envelopes on OS transport events. Both accept a host-bridge option (`HostKeysBridge` / `HostMediaBridge`) so Electron / Tauri / native shells can swap in OS-level backends without re-implementing the wire-protocol bookkeeping.
 - `createNotifyService` handles direct `notify.*` envelopes. It is not an INC
   topic handler.
-- `createOutboxService` supports `outbox.getEvent` from draft NAP-OUTBOX. Single-event lookups run through shell-owned relay routing and only return events whose ID matches the request. The draft wire contract keeps `outbox.query` one-shot and `outbox.subscribe` streaming; Kehto's concrete `createRelayPoolOutboxRouter` additionally exposes host-side `queryStream()` so verified query events can arrive before asynchronous NIP-65 discovery completes.
-- `createResourceService` implements the draft NAP-RESOURCE request lifecycle and current result shapes without choosing a runtime's network policy. By default it delegates every syntactically valid URL to the injected `fetch` resolver; `resource.info.schemes` is advisory and never authorizes or blocks a request. Runtimes that want origin grants can supply `isOriginGranted`, `getConnectGrants`, and `resolveIdentity` together, while permissive runtimes can omit all three. The service enforces supplied size/bulk caps, scopes cancellation to the requesting window, drops cancelled terminal envelopes, never forwards response headers, and preserves explicit `ResourceServiceError` codes from the resolver. Browser fetch failures, including responses hidden by CORS, use the canonical `network-error`; a resolver that can read the bytes returns them normally.
+- `createOutboxService` supports `outbox.getEvent` from draft NAP-OUTBOX. Single-event lookups run through shell-owned relay routing and only return events whose ID matches the request. Hosts can provide `getReadRouter` to scope all event-returning reads (`getEvent`, query, and subscription) to the authenticated source window, plus `getQueryRouter` when one-shot queries need an additional decorator. The draft wire contract keeps `outbox.query` one-shot and `outbox.subscribe` streaming; Kehto's concrete `createRelayPoolOutboxRouter` additionally exposes host-side `queryStream()` so verified query events can arrive before asynchronous NIP-65 discovery completes.
+- `createResourceService` implements NAP-RESOURCE at exact draft head `9511232f69313aa7953d110e35d32cc28d506f66` without choosing a runtime's network policy. Single requests carry optional advisory Blossom `servers`; bulk requests use canonical per-resource `requests: [{ url, servers? }]` entries. The service forwards hints to the injected resolver only for `blossom:`, preserves order and per-entry failures, and exposes optional `resource.info.maxServers`. By default it delegates every syntactically valid URL to the resolver; `resource.info.schemes` remains advisory. Runtimes that want hierarchical-origin grants can supply `isOriginGranted`, `getConnectGrants`, and `resolveIdentity` together, while scheme resolvers retain responsibility for hint validation, SSRF protection, redirects, and fallback policy. The service enforces supplied size/bulk caps, scopes cancellation to the requesting window, drops cancelled terminal envelopes, never forwards response headers, and preserves explicit `ResourceServiceError` codes.
 - `createUploadService` supports `upload.info` from draft NAP-UPLOAD. Hosts may expose configured rails, return URL forms, maximum bytes, and MIME type policy without requiring napplets to start an upload.
 - `createConfigService` implements draft NAP-CONFIG's shell-writer boundary: recursive bounded-subset schema validation, per-window schema/subscription state, deterministic defaults, invalid/orphan removal, version rollback rejection, scoped host persistence hooks, and settings-UI commits. Reads before schema registration fail closed with `no-schema`.
 - `createDmService` keeps NAP-DM request correlation, per-window subscriptions, and packaged message shapes in runtime-owned code. Adapters cover concrete transports: verified NIP-17 gift wraps and relay history via `nostr-tools`, structural NDR runtimes with relay hooks, and Cordn/ContextVM coordinator clients.

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { MediaAction } from '@napplet/nap/media/types';
 import { NotifyActionMessage, NotifyClickedMessage, NotifyDismissedMessage, NotifySendMessage, NotifyChannelRegisterMessage, NotifyControl } from '@napplet/nap/notify/types';
 import { Theme, ThemeChangedMessage } from '@napplet/nap/theme/types';
 import { ConfigSchemaErrorCode, NappletConfigSchema, ConfigValues } from '@napplet/nap/config/types';
+import { ResourceInfo } from '@napplet/nap/resource/types';
+export { ResourceBytesRequest, ResourceInfo, ResourceSchemeInfo } from '@napplet/nap/resource/types';
 export { a as CvmCloseMessage, b as CvmCloseResultMessage, c as CvmDiscoverMessage, d as CvmDiscoverQuery, e as CvmDiscoverResultMessage, f as CvmEventMessage, g as CvmInboundMessage, h as CvmOutboundMessage, i as CvmRequestMessage, j as CvmRequestOptions, k as CvmRequestResultMessage, l as CvmServer, m as CvmServerRef, n as CvmService, o as CvmServiceOptions, C as CvmTransport, p as CvmTransportError, M as McpContentBlock, q as McpMessage, r as McpTool, s as McpToolResult, t as createCvmService } from './cvm-service-t5syG4tU.js';
 
 /**
@@ -1406,16 +1408,18 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  * ```
  */
 
-/** Runtime-disclosed support for one resource URL scheme. */
-interface ResourceSchemeInfo {
-    scheme: string;
-    enabled: boolean;
-}
-/** Advisory resource capability and policy limits disclosed by the runtime. */
-interface ResourceInfo {
-    schemes: ResourceSchemeInfo[];
-    maxBytes?: number;
-    maxUrls?: number;
+/** Read-only metadata passed from the resource service to a runtime resolver. */
+interface ResourceFetchInit {
+    /** Read-only HTTP method selected by the service. */
+    method?: string;
+    /** Optional runtime-owned request headers. */
+    headers?: Record<string, string>;
+    /** Request-scoped cancellation signal. */
+    signal: AbortSignal;
+    /** Authenticated source window, for runtime-private scoped policy state. */
+    windowId?: string;
+    /** Advisory Blossom server origins for this resource only. */
+    servers?: readonly string[];
 }
 /** Context passed to a host-provided resource info resolver. */
 interface ResourceInfoContext {
@@ -1445,13 +1449,9 @@ interface ResourceServiceOptions {
      * canonical protocol error classification.
      *
      * @param url - The URL from the resource.bytes request
-     * @param init - Read-only method and request-scoped AbortSignal
+     * @param init - Read-only method, request-scoped AbortSignal, and optional advisory Blossom servers
      */
-    fetch(url: string, init: {
-        method?: string;
-        headers?: Record<string, string>;
-        signal: AbortSignal;
-    }): Promise<Response>;
+    fetch(url: string, init: ResourceFetchInit): Promise<Response>;
     /**
      * Returns true if `origin` is present in `grants` (the list returned by
      * `getConnectGrants` for the napplet's dTag + aggregateHash).
@@ -1717,7 +1717,19 @@ interface OutboxServiceOptions {
     /** The outbox router the shell uses to reach relays. Required. */
     router: OutboxRouter;
     /**
-     * Optionally selects a request-scoped router for a live napplet source.
+     * Optionally selects a source-scoped router for event-returning reads.
+     *
+     * The selected router is used for `outbox.getEvent`, `outbox.query`, and
+     * `outbox.subscribe`. A query-specific router takes precedence when both
+     * hooks are supplied.
+     *
+     * @param windowId - The authenticated source window for the request.
+     * @param context - Narrow runtime context for source-bound policy checks.
+     * @returns Router used for that source's event-returning reads.
+     */
+    getReadRouter?(windowId: string, context: ServiceRuntimeContext | undefined): OutboxRouter;
+    /**
+     * Optionally selects a query-specific router for a live napplet source.
      *
      * @param windowId - The authenticated source window for the request.
      * @param context - Narrow runtime context for source-bound policy checks.
@@ -2849,4 +2861,4 @@ interface FsService extends ServiceHandler {
  */
 declare function createFsService(options: FsServiceOptions): FsService;
 
-export { type BleServiceContext, type BleServiceOptions, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type CommonServiceContext, type CommonServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type ConfigSettingsContext, type CoordinatedRelayOptions, type CordnCodecResult, type CordnCoordinatorClient, type CordnCoordinatorSubscription, type CordnDmAdapterOptions, type CordnDmClient, type CordnGroupMessage, type CordnRelayCoordinatorOptions, type CountRequest, type CountResult, type CountServiceOptions, type DmAdapter, DmMemoryStore, type DmRelayPool, type DmService, type DmServiceOptions, type FsBackend, type FsBackendChange, type FsBackendWatch, type FsService, FsServiceError, type FsServiceOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentCatalogEntry, type IntentDispatchParams, type IntentResolver, type IntentResolverContext, type IntentServiceOptions, type IntentTargetController, type IntentTargetDispatch, type KeysServiceOptions, type LinkOpenContext, type LinkServiceOptions, type ListsServiceContext, type ListsServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NdrDmAdapterOptions, type NdrRelayTransport, type NdrRelayTransportOptions, type NdrRumorLike, type NdrRuntimeLike, type Nip17DmAdapterOptions, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyInteractionMessage, type NotifyPresentation, type NotifyServiceOptions, type OutboxEventOptions, type OutboxEventResult, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxQueryStream, type OutboxQueryStreamSink, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceErrorCode, type ResourceInfo, type ResourceInfoContext, type ResourceInfoProvider, type ResourceSchemeInfo, type ResourceService, ResourceServiceError, type ResourceServiceOptions, type SerialServiceContext, type SerialServiceOptions, type SignEvent, type StreamingOutboxRouter, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadInfo, type UploadInfoContext, type UploadInfoProvider, type UploadRail, type UploadRailInfo, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type WebrtcServiceContext, type WebrtcServiceOptions, createBleService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createCommonService, createConfigService, createCoordinatedRelay, createCordnDmAdapter, createCordnRelayCoordinatorClient, createCountService, createDmService, createFsService, createHttpUploader, createIdentityService, createIntentService, createKeysService, createLinkService, createListsService, createMediaService, createNdrDmAdapter, createNdrRelayTransport, createNip17DmAdapter, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createSerialService, createThemeService, createUploadService, createWebrtcService, manifestToIntentCatalogEntry, resolveConfigValues, validateConfigSchema };
+export { type BleServiceContext, type BleServiceOptions, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type CommonServiceContext, type CommonServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type ConfigSettingsContext, type CoordinatedRelayOptions, type CordnCodecResult, type CordnCoordinatorClient, type CordnCoordinatorSubscription, type CordnDmAdapterOptions, type CordnDmClient, type CordnGroupMessage, type CordnRelayCoordinatorOptions, type CountRequest, type CountResult, type CountServiceOptions, type DmAdapter, DmMemoryStore, type DmRelayPool, type DmService, type DmServiceOptions, type FsBackend, type FsBackendChange, type FsBackendWatch, type FsService, FsServiceError, type FsServiceOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentCatalogEntry, type IntentDispatchParams, type IntentResolver, type IntentResolverContext, type IntentServiceOptions, type IntentTargetController, type IntentTargetDispatch, type KeysServiceOptions, type LinkOpenContext, type LinkServiceOptions, type ListsServiceContext, type ListsServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NdrDmAdapterOptions, type NdrRelayTransport, type NdrRelayTransportOptions, type NdrRumorLike, type NdrRuntimeLike, type Nip17DmAdapterOptions, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyInteractionMessage, type NotifyPresentation, type NotifyServiceOptions, type OutboxEventOptions, type OutboxEventResult, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxQueryStream, type OutboxQueryStreamSink, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceErrorCode, type ResourceFetchInit, type ResourceInfoContext, type ResourceInfoProvider, type ResourceService, ResourceServiceError, type ResourceServiceOptions, type SerialServiceContext, type SerialServiceOptions, type SignEvent, type StreamingOutboxRouter, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadInfo, type UploadInfoContext, type UploadInfoProvider, type UploadRail, type UploadRailInfo, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type WebrtcServiceContext, type WebrtcServiceOptions, createBleService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createCommonService, createConfigService, createCoordinatedRelay, createCordnDmAdapter, createCordnRelayCoordinatorClient, createCountService, createDmService, createFsService, createHttpUploader, createIdentityService, createIntentService, createKeysService, createLinkService, createListsService, createMediaService, createNdrDmAdapter, createNdrRelayTransport, createNip17DmAdapter, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createSerialService, createThemeService, createUploadService, createWebrtcService, manifestToIntentCatalogEntry, resolveConfigValues, validateConfigSchema };

package/dist/index.js

@@ -2336,7 +2336,8 @@ function normalizeResourceInfo(info) {
   return {
     schemes: Array.isArray(info.schemes) ? info.schemes.filter((scheme) => typeof scheme?.scheme === "string").map((scheme) => ({ scheme: scheme.scheme, enabled: scheme.enabled !== false })) : [],
     ...typeof info.maxBytes === "number" ? { maxBytes: info.maxBytes } : {},
-    ...typeof info.maxUrls === "number" ? { maxUrls: info.maxUrls } : {}
+    ...typeof info.maxUrls === "number" ? { maxUrls: info.maxUrls } : {},
+    ...typeof info.maxServers === "number" ? { maxServers: info.maxServers } : {}
   };
 }
 async function resolveResourceInfo(options, windowId) {
@@ -2375,10 +2376,11 @@ function classifyResourceFailure(error) {
     message: error instanceof Error ? error.message : String(error)
   };
 }
-async function fetchResourceItem(options, windowId, info, url, signal) {
+async function fetchResourceItem(options, windowId, info, request, signal) {
+  const { url } = request;
   const parsedUrl = parseResourceUrl(url);
   if (!parsedUrl) return resourceInvalidRequest(url, `invalid URL: ${url}`);
-  if (options.isOriginGranted && options.getConnectGrants) {
+  if (parsedUrl.origin !== "null" && options.isOriginGranted && options.getConnectGrants) {
     const identity = options.resolveIdentity?.(windowId) ?? null;
     if (!identity) {
       return {
@@ -2402,7 +2404,9 @@ async function fetchResourceItem(options, windowId, info, url, signal) {
   try {
     const response = await options.fetch(url, {
       method: "GET",
-      signal
+      signal,
+      windowId,
+      ...parsedUrl.protocol === "blossom:" && request.servers !== void 0 ? { servers: [...request.servers] } : {}
     });
     const buffer = await response.arrayBuffer();
     if (info.maxBytes !== void 0 && buffer.byteLength > info.maxBytes) {
@@ -2426,12 +2430,12 @@ async function fetchResourceItem(options, windowId, info, url, signal) {
   }
 }
 async function handleBytes(options, state, windowId, msg, send) {
-  const { requestId, url } = msg;
+  const { requestId, ...request } = msg;
   const controller = new AbortController();
   trackRequest(state, requestId, windowId, controller);
   try {
     const info = await resolveResourceInfo(options, windowId);
-    const item = await fetchResourceItem(options, windowId, info, url, controller.signal);
+    const item = await fetchResourceItem(options, windowId, info, request, controller.signal);
     if (controller.signal.aborted) return;
     if (!item.ok) {
       sendResourceError(send, requestId, item.message, item.error);
@@ -2453,9 +2457,9 @@ async function handleBytes(options, state, windowId, msg, send) {
   }
 }
 async function handleBytesMany(options, state, windowId, msg, send) {
-  const { requestId, urls } = msg;
-  if (!Array.isArray(urls) || urls.length === 0 || urls.some((url) => typeof url !== "string")) {
-    sendBytesManyError(send, requestId, "resource.bytesMany requires a non-empty urls array", "invalid-request");
+  const { requestId, requests } = msg;
+  if (!isResourceRequestList(requests)) {
+    sendBytesManyError(send, requestId, "resource.bytesMany requires a non-empty requests array", "invalid-request");
     return;
   }
   let info;
@@ -2466,7 +2470,7 @@ async function handleBytesMany(options, state, windowId, msg, send) {
     sendBytesManyError(send, requestId, failure.message, failure.error);
     return;
   }
-  if (info.maxUrls !== void 0 && urls.length > info.maxUrls) {
+  if (info.maxUrls !== void 0 && requests.length > info.maxUrls) {
     sendBytesManyError(send, requestId, `resource.bytesMany exceeds ${info.maxUrls} URLs`, "too-large");
     return;
   }
@@ -2474,8 +2478,8 @@ async function handleBytesMany(options, state, windowId, msg, send) {
   trackRequest(state, requestId, windowId, controller);
   try {
     const items = [];
-    for (const url of urls) {
-      const item = await fetchResourceItem(options, windowId, info, url, controller.signal);
+    for (const request of requests) {
+      const item = await fetchResourceItem(options, windowId, info, request, controller.signal);
       if (controller.signal.aborted) return;
       if (item.ok) {
         items.push({
@@ -2507,6 +2511,12 @@ async function handleBytesMany(options, state, windowId, msg, send) {
     untrackRequest(state, windowId, requestId);
   }
 }
+function hasValidServerHints(request) {
+  return request.servers === void 0 || Array.isArray(request.servers) && request.servers.every((server) => typeof server === "string");
+}
+function isResourceRequestList(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((request) => typeof request === "object" && request !== null && typeof request.url === "string" && hasValidServerHints(request));
+}
 function handleCancel(state, windowId, requestId) {
   const entry = state.inFlight.get(requestKey(windowId, requestId));
   if (entry) {
@@ -2544,11 +2554,15 @@ function createResourceService(options) {
           const m = message;
           const requestId = requestIdFromMessage(m);
           if (!requestId) return;
-          if (typeof m.url !== "string") {
-            sendResourceError(send, requestId, "resource.bytes requires a URL", "invalid-request");
+          if (typeof m.url !== "string" || !hasValidServerHints(m)) {
+            sendResourceError(send, requestId, "resource.bytes requires a URL and optional string servers", "invalid-request");
             return;
           }
-          handleBytes(options, state, windowId, { requestId, url: m.url }, send).catch(() => {
+          handleBytes(options, state, windowId, {
+            requestId,
+            url: m.url,
+            ...m.servers !== void 0 ? { servers: [...m.servers] } : {}
+          }, send).catch(() => {
           });
           return;
         }
@@ -2564,7 +2578,7 @@ function createResourceService(options) {
           const m = message;
           const requestId = requestIdFromMessage(m);
           if (!requestId) return;
-          handleBytesMany(options, state, windowId, { requestId, urls: m.urls ?? [] }, send).catch(() => {
+          handleBytesMany(options, state, windowId, { requestId, requests: m.requests ?? [] }, send).catch(() => {
           });
           return;
         }
@@ -2707,7 +2721,7 @@ function createOutboxService(options) {
   if (!options || typeof options.router !== "object" || options.router === null) {
     throw new Error("createOutboxService: options.router is required");
   }
-  const { router, getQueryRouter } = options;
+  const { router, getReadRouter, getQueryRouter } = options;
   let runtimeContext;
   const subscriptions = /* @__PURE__ */ new Map();
   function handleQuery(windowId, msg, send) {
@@ -2718,7 +2732,7 @@ function createOutboxService(options) {
       send({ type: "outbox.query.result", id, events: [], error: "invalid filter" });
       return;
     }
-    const queryRouter = getQueryRouter?.(windowId, runtimeContext) ?? router;
+    const queryRouter = getQueryRouter?.(windowId, runtimeContext) ?? getReadRouter?.(windowId, runtimeContext) ?? router;
     void queryRouter.query(filters, sanitizeQueryOptions(m.options)).then(
       (result2) => send({
         type: "outbox.query.result",
@@ -2750,7 +2764,8 @@ function createOutboxService(options) {
         send({ type: "outbox.closed", subId, ...reason === void 0 ? {} : { reason } });
       }
     };
-    subscriptions.set(subKey, router.subscribe(filters, sanitizeSubscribeOptions(m.options), sink));
+    const readRouter = getReadRouter?.(windowId, runtimeContext) ?? router;
+    subscriptions.set(subKey, readRouter.subscribe(filters, sanitizeSubscribeOptions(m.options), sink));
   }
   function handleClose(windowId, msg, send) {
     const m = msg;
@@ -2805,7 +2820,7 @@ function createOutboxService(options) {
     handleMessage(windowId, message, send) {
       switch (message.type) {
         case "outbox.getEvent":
-          handleGetEvent(router, message, send);
+          handleGetEvent(getReadRouter?.(windowId, runtimeContext) ?? router, message, send);
           return;
         case "outbox.query":
           handleQuery(windowId, message, send);