@kehto/services 0.20.0 → 0.20.1

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.
 
@@ -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 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.
 - `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

@@ -1372,16 +1372,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,11 +1391,18 @@ 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);
  * ```
  */
 
@@ -1421,25 +1430,22 @@ 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 and request-scoped AbortSignal
      */
     fetch(url: string, init: {
         method?: string;
@@ -1449,6 +1455,8 @@ interface ResourceServiceOptions {
     /**
      * 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 +1464,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 +1485,7 @@ interface ResourceServiceOptions {
      *
      * @param windowId - The iframe window identifier
      */
-    resolveIdentity(windowId: string): {
+    resolveIdentity?(windowId: string): {
         dTag: string;
         aggregateHash: string;
     } | null;
@@ -1487,8 +1493,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 +1504,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 +1520,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 +1535,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,

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);
@@ -2332,7 +2341,7 @@ function normalizeResourceInfo(info) {
 }
 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,22 +2375,29 @@ 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, url, signal) {
   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 (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, {
@@ -2411,16 +2427,11 @@ 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 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, url, controller.signal);
     if (controller.signal.aborted) return;
     if (!item.ok) {
       sendResourceError(send, requestId, item.message, item.error);
@@ -2447,11 +2458,6 @@ async function handleBytesMany(options, state, windowId, msg, send) {
     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");
-    return;
-  }
   let info;
   try {
     info = await resolveResourceInfo(options, windowId);
@@ -2469,7 +2475,7 @@ async function handleBytesMany(options, state, windowId, msg, send) {
   try {
     const items = [];
     for (const url of urls) {
-      const item = await fetchResourceItem(options, identity, info, url, controller.signal);
+      const item = await fetchResourceItem(options, windowId, info, url, controller.signal);
       if (controller.signal.aborted) return;
       if (item.ok) {
         items.push({
@@ -2528,7 +2534,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,