@jini-ai/platform 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @jini-ai/platform
 
+## 0.5.7 — 2026-10-14
+
+- The asset cache's optional `undici` load moves behind `asset-cache.adapter.ts` (64eafe35); injected dispatchers, DNS validation and the MODULE_NOT_FOUND message are unchanged. No API change.
+
+## 0.5.6 — 2026-10-13
+
+- `undici` and `hast-util-from-parse5`, `hast-util-to-mdast`, `mdast-util-to-markdown`, `mdast-util-gfm-table` (with `parse5`) are now optional peers instead of dependencies. Only `./web` needs the HTML/Markdown set; only the default `createAssetCacheDispatcher` needs undici, loaded lazily (a missing peer throws `AssetCacheError` 500; a host-supplied dispatcher needs none). Hosts using those must list the packages themselves.
+- New `./asset-cache` subpath (node) exporting the asset cache without the root barrel.
+- New universal `./secrets/credential-sets/contracts` leaf (vault contracts without the vault runtime); `@jini-ai/db` 0.3.4's SQL vault repo imports it.
+
 ## 0.5.5 — 2026-10-13
 
 - New narrow subpaths for the existing OS helpers: `./command`, `./process`, `./toolchain`, `./proxy-env`, `./shell`, `./child-environment`. Importing one loads 1-2 modules instead of the root barrel's 181 (incl. undici). The root still exports everything; no signature change.

package/README.md

@@ -14,8 +14,14 @@ that were split out of OD's monolithic daemon (see the archived provenance ledge
 npm install @jini-ai/platform
 ```
 
-No peer dependencies. `undici` is a regular dependency (used by the SSRF-safe asset cache's
-connection-time DNS-rebinding guard). Interactive terminal sessions (`createTerminalService`)
+`undici@^7.25.0` is an optional peer for the SSRF-safe asset cache's default dispatcher.
+Install it when calling `createAssetCacheDispatcher` or creating a cache without a host-supplied
+guarded dispatcher. Root imports and `@jini-ai/platform/asset-cache` imports do not load undici;
+the synchronous factory loads it on demand and reports a missing-peer error if it is absent.
+The root declarations retain undici types, so TypeScript consumers of those declarations also
+need the peer available. The dispatcher validates DNS at connection time, and cache `close()`
+closes only its default dispatcher; a host-supplied dispatcher remains owned by the host.
+Interactive terminal sessions (`createTerminalService`)
 need a `PtySpawn` implementation supplied by the caller — this package defines the `PtyProcess`/
 `PtySpawn` port only, it does not depend on `node-pty` itself, so bring your own adapter (or use
 `@jini-ai/daemon`'s, which wires a real `node-pty` behind the same port).
@@ -92,6 +98,20 @@ The package also exposes `./http/guarded`, `./mail`, `./mail/smtp`,
 `./fs/guarded-reader`, `./fs/durable-json`, and `./secrets`. New APIs take a required
 object followed by an optional object. Application identity and policy values belong to the caller.
 
+`@jini-ai/platform/web` loads these optional peers at import time: `parse5@7.3.0`,
+`hast-util-from-parse5@8.0.3`, `hast-util-to-mdast@10.1.2`,
+`mdast-util-to-markdown@2.1.2`, and `mdast-util-gfm-table@2.0.0`. Install all five
+when using that subpath; the other entries do not load them. Existing web consumers that
+relied on transitive installation must add them before upgrading.
+
+```sh
+npm install parse5@7.3.0 hast-util-from-parse5@8.0.3 hast-util-to-mdast@10.1.2 mdast-util-to-markdown@2.1.2 mdast-util-gfm-table@2.0.0
+```
+
+The isolation metadata shares only the address classifiers (including their literal
+endpoint policy), timeout wrapper and egress refusal class across domains. These
+leaves retain one owner so HTTP and web adapters use the same security decisions.
+
 ```ts
 import { createHttpClient, createNodeGuardedHttpPorts, guardedFetch } from "@jini-ai/platform/http/guarded";
 

package/dist/asset-cache.adapter.d.ts

@@ -0,0 +1,9 @@
+import type { LookupFunction } from 'node:net';
+import type { Agent } from 'undici';
+/** Load the optional vendor only for a default dispatcher; the cache owns lookup validation.
+ * @throws When the optional peer cannot be loaded or its Agent cannot be constructed.
+ */
+export declare function createUndiciAssetCacheDispatcher({ lookup }: {
+    lookup: LookupFunction;
+}, _options?: Record<string, never>): Agent;
+//# sourceMappingURL=asset-cache.adapter.d.ts.map

package/dist/asset-cache.adapter.js

@@ -0,0 +1,10 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+/** Load the optional vendor only for a default dispatcher; the cache owns lookup validation.
+ * @throws When the optional peer cannot be loaded or its Agent cannot be constructed.
+ */
+export function createUndiciAssetCacheDispatcher({ lookup }, _options = {}) {
+    const { Agent } = require('undici');
+    return new Agent({ connect: { lookup } });
+}
+//# sourceMappingURL=asset-cache.adapter.js.map

package/dist/asset-cache.d.ts

@@ -1,5 +1,5 @@
 import { lookup as dnsLookupCb } from 'node:dns';
-import { Agent, type Dispatcher } from 'undici';
+import type { Agent, Dispatcher } from 'undici';
 /** Media extensions we are willing to cache + proxy. Anything else (HTML,
  *  CSS, JS, fonts) is intentionally left alone so this surface never becomes a
  *  general-purpose open proxy. */
@@ -52,7 +52,9 @@ export interface AssetCache {
     /** Closes only the default adapter; an injected dispatcher remains owned by its host. */
     close?(): Promise<void>;
 }
-/** Default adapter: validate DNS at connection time, so the checked address is the connected one. */
+/** Default adapter: validate DNS at connection time, so the checked address is the connected one.
+ * @throws {AssetCacheError} When the host has not installed the optional undici peer.
+ */
 export declare function createAssetCacheDispatcher(_required: Record<string, never>, { lookupImpl }?: {
     lookupImpl?: DnsLookupCb;
 }): Agent;

package/dist/asset-cache.js

@@ -24,7 +24,7 @@ import { lookup as dnsLookupCb } from 'node:dns';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { isIP } from 'node:net';
 import path from 'node:path';
-import { Agent } from 'undici';
+import { createUndiciAssetCacheDispatcher } from './asset-cache.adapter.js';
 import { isPrivateAddress } from './net/address.js';
 /** Media extensions we are willing to cache + proxy. Anything else (HTML,
  *  CSS, JS, fonts) is intentionally left alone so this surface never becomes a
@@ -127,9 +127,21 @@ export function createValidatingLookup(lookupImpl = dnsLookupCb) {
         });
     };
 }
-/** Default adapter: validate DNS at connection time, so the checked address is the connected one. */
+/** Default adapter: validate DNS at connection time, so the checked address is the connected one.
+ * @throws {AssetCacheError} When the host has not installed the optional undici peer.
+ */
 export function createAssetCacheDispatcher(_required, { lookupImpl } = {}) {
-    return new Agent({ connect: { lookup: createValidatingLookup(lookupImpl) } });
+    // Keep the factory synchronous while root imports and host-supplied dispatchers need no undici.
+    try {
+        return createUndiciAssetCacheDispatcher({ lookup: createValidatingLookup(lookupImpl) });
+    }
+    catch (error) {
+        if (error instanceof Error && error.code === 'MODULE_NOT_FOUND'
+            && error.message.split('\n')[0] === "Cannot find module 'undici'") {
+            throw new AssetCacheError(500, 'Asset cache dispatcher requires the optional peer "undici"; install undici@^7.25.0 or supply a guarded dispatcher.');
+        }
+        throw error;
+    }
 }
 /** Build a disk-backed cache for external sandboxed-content media. Concurrent
  *  requests for the same URL share one in-flight fetch; completed fetches

package/dist/fetch-with-timeout.d.ts

@@ -36,7 +36,8 @@
  * **Also exported as its own subpath, `@jini-ai/platform/fetch-with-timeout`, deliberately.** This
  * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
  * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
- * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, `undici`'s `Agent`, etc.
+ * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, etc.; the asset-cache
+ * dispatcher loads the optional `undici` peer only when its synchronous factory is called.
  * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
  * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
  * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is

package/dist/fetch-with-timeout.js

@@ -36,7 +36,8 @@
  * **Also exported as its own subpath, `@jini-ai/platform/fetch-with-timeout`, deliberately.** This
  * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
  * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
- * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, `undici`'s `Agent`, etc.
+ * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, etc.; the asset-cache
+ * dispatcher loads the optional `undici` peer only when its synchronous factory is called.
  * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
  * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
  * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is

package/dist/secrets/credential-sets/contracts.d.ts

@@ -0,0 +1,6 @@
+/** Universal vault contracts and invariants, without service, keyring or storage adapters.
+ * Re-export the owner so aggregate callers and persistence adapters share VaultError identity.
+ * @example import { VaultError, type VaultRepoPort } from "@jini-ai/platform/secrets/credential-sets/contracts";
+ */
+export * from "./vault.types.js";
+//# sourceMappingURL=contracts.d.ts.map

package/dist/secrets/credential-sets/contracts.js

@@ -0,0 +1,6 @@
+/** Universal vault contracts and invariants, without service, keyring or storage adapters.
+ * Re-export the owner so aggregate callers and persistence adapters share VaultError identity.
+ * @example import { VaultError, type VaultRepoPort } from "@jini-ai/platform/secrets/credential-sets/contracts";
+ */
+export * from "./vault.types.js";
+//# sourceMappingURL=contracts.js.map

package/dist/web/index.d.ts

@@ -1,4 +1,5 @@
-/** Public-page projections and an anonymous reader over injected guarded HTTP ports. */
+/** Public-page projections and an anonymous reader over injected guarded HTTP ports.
+ * Importing this entry requires the optional `parse5` peer listed in README.md. */
 export * from "./web-page.js";
 export * from "./html-document.js";
 export { htmlToMarkdown } from "./html-to-markdown.js";

package/dist/web/index.js

@@ -1,4 +1,5 @@
-/** Public-page projections and an anonymous reader over injected guarded HTTP ports. */
+/** Public-page projections and an anonymous reader over injected guarded HTTP ports.
+ * Importing this entry requires the optional `parse5` peer listed in README.md. */
 export * from "./web-page.js";
 export * from "./html-document.js";
 export { htmlToMarkdown } from "./html-to-markdown.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/platform",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Generic OS/platform primitives: process exec and lifecycle, filesystem containment, HTTP readiness polling, toolchain discovery, blob storage, AWS signing, and an SSRF-safe asset cache.",
   "license": "Apache-2.0",
   "repository": {
@@ -15,8 +15,10 @@
     "entries": {
       ".": "node",
       "./fetch-with-timeout": "node",
+      "./asset-cache": "node",
       "./secrets": "node",
       "./secrets/credential-sets": "node",
+      "./secrets/credential-sets/contracts": "universal",
       "./secrets/testing": "node",
       "./http/guarded": "node",
       "./mail": "node",
@@ -44,7 +46,13 @@
         "./proxy-env": "os",
         "./shell": "os",
         "./child-environment": "os"
-      }
+      },
+      "shared": [
+        "src/net/address.ts",
+        "src/net/endpoint-policy.ts",
+        "src/fetch-with-timeout.ts",
+        "src/http/guarded/errors.ts"
+      ]
     }
   },
   "type": "module",
@@ -62,6 +70,11 @@
       "import": "./dist/fetch-with-timeout.js",
       "default": "./dist/fetch-with-timeout.js"
     },
+    "./asset-cache": {
+      "types": "./dist/asset-cache.d.ts",
+      "import": "./dist/asset-cache.js",
+      "default": "./dist/asset-cache.js"
+    },
     "./secrets": {
       "types": "./dist/secrets/index.d.ts",
       "import": "./dist/secrets/index.js",
@@ -72,6 +85,11 @@
       "import": "./dist/secrets/credential-sets/index.js",
       "default": "./dist/secrets/credential-sets/index.js"
     },
+    "./secrets/credential-sets/contracts": {
+      "types": "./dist/secrets/credential-sets/contracts.d.ts",
+      "import": "./dist/secrets/credential-sets/contracts.js",
+      "default": "./dist/secrets/credential-sets/contracts.js"
+    },
     "./secrets/testing": {
       "types": "./dist/secrets/testing.d.ts",
       "import": "./dist/secrets/testing.js",
@@ -176,20 +194,48 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "undici": "^7.25.0",
-    "@jini-ai/core": "^0.4.0",
-    "parse5": "7.3.0",
-    "hast-util-from-parse5": "8.0.3",
-    "hast-util-to-mdast": "10.1.2",
-    "mdast-util-to-markdown": "2.1.2",
-    "mdast-util-gfm-table": "2.0.0"
+    "@jini-ai/core": "^0.4.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.9"
+    "@vitest/coverage-v8": "^2.1.9",
+    "undici": "^7.25.0",
+    "hast-util-from-parse5": "8.0.3",
+    "hast-util-to-mdast": "10.1.2",
+    "mdast-util-to-markdown": "2.1.2",
+    "mdast-util-gfm-table": "2.0.0",
+    "parse5": "7.3.0"
+  },
+  "peerDependencies": {
+    "undici": "^7.25.0",
+    "hast-util-from-parse5": "8.0.3",
+    "hast-util-to-mdast": "10.1.2",
+    "mdast-util-to-markdown": "2.1.2",
+    "mdast-util-gfm-table": "2.0.0",
+    "parse5": "7.3.0"
+  },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    },
+    "hast-util-from-parse5": {
+      "optional": true
+    },
+    "hast-util-to-mdast": {
+      "optional": true
+    },
+    "mdast-util-to-markdown": {
+      "optional": true
+    },
+    "mdast-util-gfm-table": {
+      "optional": true
+    },
+    "parse5": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",