@kehto/services 0.20.0 → 0.21.0

package/README.md

@@ -4,7 +4,7 @@ Reference service handlers for the napplet protocol — identity, relay pool,
 cache, keys, media, notify, theme, link, common, lists, serial, BLE, WebRTC,
 and DM.
 
-> **Alpha status:** Kehto is an early runtime implementation for a draft NIP-5D
+> **Alpha status:** Kehto is an early runtime toolkit for a draft NIP-5D
 > protocol. NAP contracts and service envelopes are not final; treat these
 > handlers as reference implementations for the current draft.
 
@@ -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
@@ -44,7 +44,7 @@ Current draft posture:
 - `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. It fail-closes when no scheme is configured, checks per-identity origin grants, enforces disclosed size/bulk caps, scopes cancellation to the requesting window, drops cancelled terminal envelopes, and never forwards response headers. The host policy fetch must return byte-classified output and owns scheme-specific SSRF, redirect, integrity, and SVG handling.
+- `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';
 
 /**
@@ -1372,16 +1374,18 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *             resource.bytesMany.result, resource.bytesMany.error
  *
  * ──────────────────────── SCOPE BOUNDARY (RESOURCE-01) ────────────────────────
- * NAP-RESOURCE is an **authenticated fetch proxy** — read-only, atomic.
+ * NAP-RESOURCE is a runtime-mediated byte resolver — read-only, atomic.
  *
- * The host fetch boundary performs scheme-specific I/O and MUST return only a
- * policy-checked, byte-classified response. This service independently enforces
- * identity, scheme disclosure, origin grants, bulk limits, response-size caps,
- * cancellation, and the current wire shape. It never forwards upstream headers.
+ * Kehto owns neutral wire lifecycle, cancellation, result projection, and
+ * policy tooling. The runtime supplies the resolver and decides whether to use
+ * the origin-grant hooks, which schemes to resolve, and which limits to expose.
+ * Advisory `resource.info` scheme disclosure never authorizes or blocks a byte
+ * request.
  * ──────────────────────────────────────────────────────────────────────────────
  *
- * Host integration: provide `fetch`, `isOriginGranted`, `getConnectGrants`,
- * and `resolveIdentity`. ALL FOUR are required from day one (H-03 prevention).
+ * Runtime integration requires only `fetch`. A runtime MAY also install the
+ * optional origin-policy adapter (`isOriginGranted`, `getConnectGrants`, and
+ * `resolveIdentity` together).
  *
  * @example
  * ```ts
@@ -1389,24 +1393,31 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *
  * const resourceSvc = createResourceService({
  *   fetch: (url, init) => globalThis.fetch(url, init),
+ * });
+ * runtime.registerService('resource', resourceSvc);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const resourceSvc = createResourceService({
+ *   fetch: (url, init) => runtimeResources.resolve(url, init),
  *   isOriginGranted: (origin, grants) => grants.includes(origin),
  *   getConnectGrants: (dTag, hash) => myOriginGrantStore.getOrigins(dTag, hash),
  *   resolveIdentity: (windowId) => sessionRegistry.getEntryByWindowId(windowId) ?? null,
  * });
- * runtime.registerService('resource', resourceSvc);
  * ```
  */
 
-/** 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;
+    /** Advisory Blossom server origins for this resource only. */
+    servers?: readonly string[];
 }
 /** Context passed to a host-provided resource info resolver. */
 interface ResourceInfoContext {
@@ -1421,34 +1432,29 @@ type ResourceInfoProvider = ResourceInfo | ((context: ResourceInfoContext) => Re
 /**
  * Options for `createResourceService` (options-as-bridge per v1.6 Decision 18).
  *
- * ALL FOUR fields are required. The factory throws at construction if any is
- * missing — H-03 prevention: the grants source (`getConnectGrants`) MUST be
- * wired from day one so there is no window where resource requests bypass the
- * grant check.
- *
- * @see PITFALLS.md:228 (H-03) — grants-source coupling must be present at construction
+ * `fetch` is the only required field. Kehto does not select a runtime's scheme
+ * or origin policy. The optional origin-policy fields form one adapter and must
+ * therefore be supplied together when a runtime chooses to use it.
  */
 interface ResourceServiceOptions {
     /**
-     * Host-supplied policy fetch implementation. Receives the URL, a partial init
-     * (method, headers, signal), and returns a sanitized `Response`.
+     * Runtime-supplied resource resolver. Receives the requested URL and returns
+     * a byte-classified `Response`.
      *
-     * The returned `content-type` MUST be derived from inspected output bytes,
-     * never an upstream header. The host boundary also owns redirect-by-redirect
-     * private-address checks, SVG rasterization, and scheme-specific integrity.
-     * Throw `ResourceServiceError` to preserve a protocol error classification.
+     * The runtime owns scheme dispatch and every NAP-RESOURCE policy decision.
+     * The returned `content-type` must describe the runtime-classified bytes, not
+     * an untrusted upstream header. Throw `ResourceServiceError` to preserve a
+     * canonical protocol error classification.
      *
      * @param url - The URL from the resource.bytes request
-     * @param init - Method, headers (from napplet), and an 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).
+     * Optional: when omitted with `getConnectGrants`, Kehto delegates directly
+     * to the runtime resolver without an origin-grant decision.
      *
      * The reference implementation is simply `grants.includes(origin)`. Host apps
      * may provide normalized-origin comparison if needed.
@@ -1456,21 +1462,19 @@ interface ResourceServiceOptions {
      * @param origin - Parsed origin of the requested URL (scheme + host + port)
      * @param grants - Readonly list from getConnectGrants for this napplet identity
      */
-    isOriginGranted(origin: string, grants: readonly string[]): boolean;
+    isOriginGranted?(origin: string, grants: readonly string[]): boolean;
     /**
      * Returns the list of allowed fetch origins for the given napplet identity.
      * Called on every `resource.bytes` request — must be synchronous and fast.
+     * Optional and paired with `isOriginGranted` plus `resolveIdentity`.
      *
      * Host-supplied grant source (e.g. a static per-dTag allowlist map, or any
      * other host-controlled policy). Returns an empty array to deny all origins.
      *
-     * H-03 prevention: REQUIRED from day one — factory throws on construction
-     * if omitted.
-     *
      * @param dTag - The napplet's d-tag (from session registry)
      * @param aggregateHash - The napplet's aggregate hash (from session registry)
      */
-    getConnectGrants(dTag: string, aggregateHash: string): readonly string[];
+    getConnectGrants?(dTag: string, aggregateHash: string): readonly string[];
     /**
      * Resolve a windowId to the napplet's identity (dTag + aggregateHash).
      * Returns null if the window is not in the session registry.
@@ -1479,7 +1483,7 @@ interface ResourceServiceOptions {
      *
      * @param windowId - The iframe window identifier
      */
-    resolveIdentity(windowId: string): {
+    resolveIdentity?(windowId: string): {
         dTag: string;
         aggregateHash: string;
     } | null;
@@ -1487,8 +1491,8 @@ interface ResourceServiceOptions {
      * Advisory NAP-RESOURCE introspection exposed through `resource.info`.
      *
      * Provide a static snapshot or a resolver when the shell wants to disclose
-     * configured schemes and coarse limits. Omit to expose the reference
-     * service's fail-closed default (no enabled schemes or numeric limits).
+     * configured schemes and coarse limits. Scheme disclosure is advisory and is
+     * never used as fetch authorization. Omit to disclose no schemes or limits.
      */
     resourceInfo?: ResourceInfoProvider;
 }
@@ -1498,7 +1502,7 @@ interface ResourceServiceOptions {
  */
 type ResourceService = ServiceHandler;
 type ResourceErrorCode = 'invalid-request' | 'not-found' | 'blocked-by-policy' | 'timeout' | 'too-large' | 'unsupported-scheme' | 'decode-failed' | 'network-error' | 'quota-exceeded';
-/** A host policy failure with a stable NAP-RESOURCE error classification. */
+/** A runtime resolver failure with a stable NAP-RESOURCE error classification. */
 declare class ResourceServiceError extends Error {
     readonly code: ResourceErrorCode;
     /**
@@ -1514,15 +1518,14 @@ declare class ResourceServiceError extends Error {
  * `resource.bytes`, `resource.bytesMany`, `resource.cancel`, and their
  * result/error envelopes.
  *
- * On-construction guard (H-03 prevention): all four options are validated at
- * factory call time. If any is missing, the factory throws immediately with a
- * message containing `[RESOURCE-01 / H-03]` so misconfigured shell apps fail
- * loudly at startup rather than silently at first dispatch.
+ * The runtime resolver is validated at construction. Runtime implementers may
+ * additionally install the origin-grant adapter; Kehto provides and enforces
+ * the hook contract without selecting the grants or requiring that policy.
  *
  * Returns a `ServiceHandler` (no `publishValues`-style surface — resource has
  * no shell-initiated push beyond the response/error path).
  *
- * @param options - REQUIRED: fetch, isOriginGranted, getConnectGrants, resolveIdentity
+ * @param options - Runtime resolver plus optional runtime-owned policy helpers
  * @returns ServiceHandler to register via `runtime.registerService('resource', handler)`
  *
  * @example
@@ -1530,7 +1533,7 @@ declare class ResourceServiceError extends Error {
  * import { createResourceService } from '@kehto/services';
  *
  * const svc = createResourceService({
- *   fetch: (url, init) => globalThis.fetch(url, init),
+ *   fetch: (url, init) => runtimeResources.resolve(url, init),
  *   isOriginGranted: (origin, grants) => grants.includes(origin),
  *   getConnectGrants: (dTag, hash) => myOriginGrantStore.getOrigins(dTag, hash),
  *   resolveIdentity: (windowId) => sessionRegistry.getEntryByWindowId(windowId) ?? null,
@@ -2844,4 +2847,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

@@ -2272,11 +2272,20 @@ function requestKey(windowId, requestId) {
   return `${windowId}\0${requestId}`;
 }
 function assertResourceOptions(options) {
-  if (typeof options?.fetch !== "function" || typeof options?.isOriginGranted !== "function" || typeof options?.getConnectGrants !== "function" || typeof options?.resolveIdentity !== "function") {
+  if (typeof options?.fetch !== "function") {
     throw new Error(
-      "[RESOURCE-01 / H-03] createResourceService requires {fetch, isOriginGranted, getConnectGrants, resolveIdentity} \u2014 all four options are required from day one. The grants source (getConnectGrants) MUST be wired at construction time to prevent unguarded fetch proxying."
+      "[RESOURCE-01] createResourceService requires a runtime-provided fetch resolver."
     );
   }
+  const hasOriginPolicy = options.isOriginGranted !== void 0 || options.getConnectGrants !== void 0;
+  if (hasOriginPolicy && (typeof options.isOriginGranted !== "function" || typeof options.getConnectGrants !== "function" || typeof options.resolveIdentity !== "function")) {
+    throw new Error(
+      "[RESOURCE-01] optional origin policy requires {isOriginGranted, getConnectGrants, resolveIdentity} together."
+    );
+  }
+  if (options.resolveIdentity !== void 0 && typeof options.resolveIdentity !== "function") {
+    throw new Error("[RESOURCE-01] resolveIdentity must be a function when provided.");
+  }
 }
 function trackRequest(state, requestId, windowId, controller) {
   const key = requestKey(windowId, requestId);
@@ -2327,12 +2336,13 @@ 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) {
   const configured = options.resourceInfo ?? DEFAULT_RESOURCE_INFO;
-  const info = typeof configured === "function" ? await configured({ windowId, identity: options.resolveIdentity(windowId) }) : configured;
+  const info = typeof configured === "function" ? await configured({ windowId, identity: options.resolveIdentity?.(windowId) ?? null }) : configured;
   return normalizeResourceInfo(info);
 }
 async function handleInfo(options, windowId, requestId, send) {
@@ -2366,27 +2376,36 @@ function classifyResourceFailure(error) {
     message: error instanceof Error ? error.message : String(error)
   };
 }
-async function fetchResourceItem(options, identity, 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}`);
-  const scheme = parsedUrl.protocol.slice(0, -1).toLowerCase();
-  if (!info.schemes.some((item) => item.enabled && item.scheme.toLowerCase() === scheme)) {
-    return { ok: false, url, error: "unsupported-scheme", message: `scheme ${scheme} is not enabled` };
-  }
-  const origin = parsedUrl.origin;
-  const grants = options.getConnectGrants(identity.dTag, identity.aggregateHash);
-  if (!options.isOriginGranted(origin, grants)) {
-    return {
-      ok: false,
-      url,
-      error: "blocked-by-policy",
-      message: `origin ${origin} not granted`
-    };
+  if (parsedUrl.origin !== "null" && options.isOriginGranted && options.getConnectGrants) {
+    const identity = options.resolveIdentity?.(windowId) ?? null;
+    if (!identity) {
+      return {
+        ok: false,
+        url,
+        error: "blocked-by-policy",
+        message: "napplet identity not resolvable for runtime origin policy"
+      };
+    }
+    const origin = parsedUrl.origin;
+    const grants = options.getConnectGrants(identity.dTag, identity.aggregateHash);
+    if (!options.isOriginGranted(origin, grants)) {
+      return {
+        ok: false,
+        url,
+        error: "blocked-by-policy",
+        message: `origin ${origin} not granted by runtime policy`
+      };
+    }
   }
   try {
     const response = await options.fetch(url, {
       method: "GET",
-      signal
+      signal,
+      ...parsedUrl.protocol === "blossom:" && request.servers !== void 0 ? { servers: [...request.servers] } : {}
     });
     const buffer = await response.arrayBuffer();
     if (info.maxBytes !== void 0 && buffer.byteLength > info.maxBytes) {
@@ -2410,17 +2429,12 @@ async function fetchResourceItem(options, identity, info, url, signal) {
   }
 }
 async function handleBytes(options, state, windowId, msg, send) {
-  const { requestId, url } = msg;
-  const identity = options.resolveIdentity(windowId);
-  if (!identity) {
-    sendResourceError(send, requestId, "napplet identity not resolvable", "blocked-by-policy");
-    return;
-  }
+  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, identity, 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);
@@ -2442,14 +2456,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");
-    return;
-  }
-  const identity = options.resolveIdentity(windowId);
-  if (!identity) {
-    sendBytesManyError(send, requestId, "napplet identity not resolvable", "blocked-by-policy");
+  const { requestId, requests } = msg;
+  if (!isResourceRequestList(requests)) {
+    sendBytesManyError(send, requestId, "resource.bytesMany requires a non-empty requests array", "invalid-request");
     return;
   }
   let info;
@@ -2460,7 +2469,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;
   }
@@ -2468,8 +2477,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, identity, 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({
@@ -2501,6 +2510,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) {
@@ -2528,7 +2543,7 @@ function createResourceService(options) {
   const descriptor = {
     name: "resource",
     version: RESOURCE_SERVICE_VERSION,
-    description: "NAP-RESOURCE reference service \u2014 shell-proxied authenticated fetch (RESOURCE-01..06)"
+    description: "NAP-RESOURCE service \u2014 runtime-resolved byte transport (RESOURCE-01..06)"
   };
   const handler = {
     descriptor,
@@ -2538,11 +2553,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;
         }
@@ -2558,7 +2577,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;
         }