@jini-ai/core 0.4.7 → 0.4.9

package/dist/fetch/index.js

@@ -1,3 +1,4 @@
 /** Framework-neutral query contracts and cache; hosts supply transport callbacks and environment ports. */
 export { DEFAULT_STALE_TIME, IDLE_RETENTION, FetchQueryCache, toQueryError } from './cache.js';
+export { missingCachedLoaderFetchError, withCachedLoaderFetch } from './loader-read.js';
 //# sourceMappingURL=index.js.map

package/dist/fetch/loader-read.d.ts

@@ -0,0 +1,16 @@
+import type { CachedLoaderDefaults, CachedLoaderOptions, QueryKey } from './types.js';
+/**
+ * The error an argument-less `load()` rejects with when its loader was created without a default
+ * `fetch`. Named, rather than left to a `TypeError: fetch is not a function` from deep inside a cache
+ * adapter, so the misuse points at the call site that needs to pass `{ key, fetch }`.
+ */
+export declare function missingCachedLoaderFetchError(key: QueryKey): Error;
+/**
+ * Runs `read` with a fully specified `{ key, fetch }`, or rejects with
+ * {@link missingCachedLoaderFetchError} when `required` (a loader's own defaults, for an argument-less
+ * `load()`) carries no fetch. It rejects BEFORE `read` runs, so a misuse never enters the shared cache:
+ * a failed fetch there would publish an error state to every observer of that key.
+ * Shared by every `FetchQueryAdapter` so each adapter's `load` stays a single straight-line call.
+ */
+export declare function withCachedLoaderFetch<T>(required: CachedLoaderDefaults<T>, read: (resolved: Pick<CachedLoaderOptions<T>, 'key' | 'fetch'>) => Promise<T>): Promise<T>;
+//# sourceMappingURL=loader-read.d.ts.map

package/dist/fetch/loader-read.js

@@ -0,0 +1,22 @@
+/**
+ * The error an argument-less `load()` rejects with when its loader was created without a default
+ * `fetch`. Named, rather than left to a `TypeError: fetch is not a function` from deep inside a cache
+ * adapter, so the misuse points at the call site that needs to pass `{ key, fetch }`.
+ */
+export function missingCachedLoaderFetchError(key) {
+    return new Error(`Cached loader for key ${JSON.stringify(key)} has no default fetch: call load({ key, fetch }) with a fetch of its own`);
+}
+/**
+ * Runs `read` with a fully specified `{ key, fetch }`, or rejects with
+ * {@link missingCachedLoaderFetchError} when `required` (a loader's own defaults, for an argument-less
+ * `load()`) carries no fetch. It rejects BEFORE `read` runs, so a misuse never enters the shared cache:
+ * a failed fetch there would publish an error state to every observer of that key.
+ * Shared by every `FetchQueryAdapter` so each adapter's `load` stays a single straight-line call.
+ */
+export function withCachedLoaderFetch(required, read) {
+    const { key, fetch } = required;
+    if (fetch === undefined)
+        return Promise.reject(missingCachedLoaderFetchError(key));
+    return read({ key, fetch });
+}
+//# sourceMappingURL=loader-read.js.map

package/dist/fetch/types.d.ts

@@ -67,13 +67,23 @@ export interface CachedLoaderOptions<T> {
     fetch: () => Promise<T>;
     staleTime?: number;
 }
+/**
+ * What a loader hook is created with: the key its `peek`/`replace` (and an argument-less `load`)
+ * address, plus an optional default `fetch`. The default is optional because a loader whose every
+ * `load` names its own `{ key, fetch }` (per-id detail lookups, per-path file reads) would otherwise
+ * have to invent a fetch that can never run. An argument-less `load()` on a loader created without
+ * one rejects with {@link missingCachedLoaderFetchError} instead of touching the cache.
+ */
+export type CachedLoaderDefaults<T> = Pick<CachedLoaderOptions<T>, "key"> & {
+    fetch?: CachedLoaderOptions<T>["fetch"] | undefined;
+};
 /**
  * A plain promise loader serves components that own their loading UI rather than consuming
  * a hook result. It shares the provider cache, including one in-flight request per key.
  */
 export interface CachedLoader<T> {
     peek: () => T | undefined;
-    load: (required?: Pick<CachedLoaderOptions<T>, "key" | "fetch">) => Promise<T>;
+    load: (required?: Pick<CachedLoaderOptions<T>, "key" | "fetch">, optional?: Pick<CachedLoaderOptions<T>, "staleTime">) => Promise<T>;
     replace: (required: {
         value: T;
     }) => void;
@@ -88,6 +98,6 @@ export interface FetchQueryAdapter {
     useInvalidate: () => (required: {
         key: QueryKey;
     }) => void;
-    useCachedLoader: <T>(required: Pick<CachedLoaderOptions<T>, "key" | "fetch">, optional?: Omit<CachedLoaderOptions<T>, "key" | "fetch">) => CachedLoader<T>;
+    useCachedLoader: <T>(required: CachedLoaderDefaults<T>, optional?: Omit<CachedLoaderOptions<T>, "key" | "fetch">) => CachedLoader<T>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/gated-mutations/gateway.js

@@ -40,13 +40,36 @@ export async function authorizeForHooks(required) {
     }
     return deps.authorizeInstance({ principalId, permission });
 }
+/** Fresh authorization gate shared by plan/confirm/execute; refuses with NOT_AUTHORIZED. */
+async function requireAuthorization(required) {
+    const { principalId, permission } = required;
+    const authResult = await authorizeForHooks(required);
+    if (!authResult.allowed) {
+        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${permission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
+    }
+}
+/** The refusal for a token that cannot be redeemed: already redeemed, otherwise expired. */
+function unredeemableTokenError(record) {
+    if (record?.status === "redeemed") {
+        return new TokenAlreadyRedeemedError({ message: `confirmation token has already been redeemed` });
+    }
+    return new TokenExpiredError({ message: `confirmation token has expired` });
+}
+/** Look up the presented token and refuse it unless it is still minted and unexpired. */
+async function loadRedeemableToken(required) {
+    const { deps, confirmationToken } = required;
+    const record = await deps.tokens.findByToken({ token: confirmationToken });
+    if (!record) {
+        throw new TokenExpiredError({ message: `confirmation token was not found` });
+    }
+    if (!isRedeemable({ record, now: nowIso({ clock: deps.clock }) }))
+        throw unredeemableTokenError(record);
+    return record;
+}
 // Planning is read-only: check read permission and derive details, never invoke executeMutation.
 export async function plan(required, _optional = {}) {
     const { deps, principalId, hooks } = required;
-    const authResult = await authorizeForHooks({ deps, hooks, principalId, permission: hooks.readPermission });
-    if (!authResult.allowed) {
-        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${hooks.readPermission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
-    }
+    await requireAuthorization({ deps, hooks, principalId, permission: hooks.readPermission });
     const { planHash, details } = await hooks.computePlan({});
     return { domain: hooks.domain, planId: deps.idGen.newId(), planHash, details };
 }
@@ -57,10 +80,7 @@ export async function confirm(required, _optional = {}) {
     if (principalKind === "agent") {
         throw new ForbiddenError({ message: `agent principals may not confirm a gated mutation`, reasonCode: "AGENT_CANNOT_CONFIRM" });
     }
-    const authResult = await authorizeForHooks({ deps, hooks, principalId, permission: hooks.mutatePermission });
-    if (!authResult.allowed) {
-        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${hooks.mutatePermission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
-    }
+    await requireAuthorization({ deps, hooks, principalId, permission: hooks.mutatePermission });
     const token = mintToken({
         planId,
         planHash,
@@ -82,20 +102,8 @@ export async function confirm(required, _optional = {}) {
 export async function execute(required, _optional = {}) {
     // Reevaluate authorization here; confirm-time permission is not authority to execute later.
     const { deps, principalId, principalKind, hooks, confirmationToken } = required;
-    const authResult = await authorizeForHooks({ deps, hooks, principalId, permission: hooks.mutatePermission });
-    if (!authResult.allowed) {
-        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${hooks.mutatePermission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
-    }
-    const record = await deps.tokens.findByToken({ token: confirmationToken });
-    if (!record) {
-        throw new TokenExpiredError({ message: `confirmation token was not found` });
-    }
-    if (!isRedeemable({ record, now: nowIso({ clock: deps.clock }) })) {
-        if (record.status === "redeemed") {
-            throw new TokenAlreadyRedeemedError({ message: `confirmation token has already been redeemed` });
-        }
-        throw new TokenExpiredError({ message: `confirmation token has expired` });
-    }
+    await requireAuthorization({ deps, hooks, principalId, permission: hooks.mutatePermission });
+    const record = await loadRedeemableToken({ deps, confirmationToken });
     const resolvedIdentity = await hooks.resolveActorClassIdentity({ principalId, principalKind });
     if (resolvedIdentity !== record.confirmerPrincipalId) {
         throw new ForbiddenError({ message: `principal '${principalId}' (kind '${principalKind}') is not the confirmer of this token`, reasonCode: "ACTOR_CLASS_MISMATCH" });
@@ -113,11 +121,8 @@ export async function execute(required, _optional = {}) {
     // Concurrent executions can pass every earlier check; atomic redemption makes the loser fail
     // before its domain mutation, preventing a second application of the same approval.
     const { redeemed, record: latestRecord } = await deps.tokens.tryRedeem({ token: confirmationToken, now: nowIso({ clock: deps.clock }) });
-    if (!redeemed) {
-        if (!latestRecord || latestRecord.status !== "redeemed")
-            throw new TokenExpiredError({ message: `confirmation token has expired` });
-        throw new TokenAlreadyRedeemedError({ message: `confirmation token has already been redeemed` });
-    }
+    if (!redeemed)
+        throw unredeemableTokenError(latestRecord);
     return hooks.executeMutation({ planHash, details });
 }
 //# sourceMappingURL=gateway.js.map

package/dist/index.d.ts

@@ -12,15 +12,23 @@ export * from './origin-validation.js';
 export * from './principal.js';
 export * from './surface-exchanges.js';
 export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
-export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
+export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, toolDiscoveryMetadata, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
+export * from './tool-exposure.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
 export * from './contribution-registry.js';
+export * from './provider-registry.js';
+export * from './object-store.js';
 export * from './naming.js';
 export type { AgentToolSideEffect, AgentToolActorClassRule, AgentToolDefinition } from './agent-tools.js';
 export * from "./registration-kit.js";
 export * from "./approval.js";
+export * from './target-scope.js';
 export * from "./native-regexp.js";
 export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, type LegacyToolAuthorizeFn, type AuthorizationPort as ToolPermissionAuthorizationPort, type RequireToolPermissionRequired, type RequireToolPermissionOptional, } from "./tool-permissions.js";
+export { evaluateFeatureFlag, type FeatureFlagDecision } from './feature-flags.js';
+export { normalizeToolInput, withNormalizationNotes, ToolInputNormalizationError, type NormalizedToolInput, type ToolInputNormalizer } from './tool-input-normalization.js';
+export { applyBatchInputs, BATCH_GUIDANCE_MARKER, withoutBatchGuidance, batchOutcomeFor, batchDescriptorFor, batchEligibilityFor, defaultBatchableTools, withBatchInput, DEFAULT_MAX_BATCH_ITEMS, type BatchableTool, type BatchEligibility, type BatchOptOut, type BatchResult, type BatchItemResult } from './batch-tool-inputs.js';
+export type { MediaProviderCatalogPolicy, MediaProviderOption, ProviderPreset, ProviderPresetKind } from './provider-catalog.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -9,14 +9,21 @@ export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
 export * from './surface-exchanges.js';
-export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
+export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, toolDiscoveryMetadata, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
+export * from './tool-exposure.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
 export * from './contribution-registry.js';
+export * from './provider-registry.js';
+export * from './object-store.js';
 export * from './naming.js';
 export * from "./registration-kit.js";
 export * from "./approval.js";
+export * from './target-scope.js';
 export * from "./native-regexp.js";
 export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, } from "./tool-permissions.js";
+export { evaluateFeatureFlag } from './feature-flags.js';
+export { normalizeToolInput, withNormalizationNotes, ToolInputNormalizationError } from './tool-input-normalization.js';
+export { applyBatchInputs, BATCH_GUIDANCE_MARKER, withoutBatchGuidance, batchOutcomeFor, batchDescriptorFor, batchEligibilityFor, defaultBatchableTools, withBatchInput, DEFAULT_MAX_BATCH_ITEMS } from './batch-tool-inputs.js';
 //# sourceMappingURL=index.js.map

package/dist/object-store.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @file The ONE object-storage contract (2026-10-21): key → bytes, with an optional public-read
+ * capability. It absorbs four overlapping shapes (cms `BlobStorePort`, capability-providers
+ * `StorageProvider`, devops `ArtifactStorePort`, platform `BlobStorage`); those stay as thin views
+ * over this one until their consumers move. Providers are keyed in a `createProviderRegistry`
+ * (`contract: 'object_store'`), default `local`.
+ *
+ * Universal: types and pure helpers only, so every storage package (all of which already depend
+ * on core) can implement it. Filesystem and network adapters live in node/host packages.
+ *
+ * Data-plane calls REJECT on a storage fault (as every existing byte port did), and report absence
+ * as `null`/`false`, never as a rejection: a caller must never mistake "the store failed" for "the
+ * object is gone". Only `ObjectStoreProvider.create` returns a `ProviderResult`, so a bad or missing
+ * setting is a refusal the host can report, not a boot crash.
+ */
+import { type ProviderDefinition, type ProviderRegistry, type ProviderResult } from './provider-registry.js';
+/** Registry contract name for object-store providers. */
+export declare const OBJECT_STORE_CONTRACT = "object_store";
+/** The built-in default provider id (local filesystem). */
+export declare const DEFAULT_OBJECT_STORE_PROVIDER_ID = "local";
+export interface ObjectStorePutOptions {
+    readonly contentType?: string;
+    /** Extra stored response headers (e.g. `content-disposition`); a provider may drop unsupported ones. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Create-only write: lands `bytes` iff no object occupies `key`, atomically with respect to any
+     * other concurrent writer of the SAME key. No adapter may implement this as a separate existence
+     * check followed by a write — that pair is exactly the TOCTOU gap this flag exists to close.
+     */
+    readonly ifAbsent?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface ObjectStoreCallOptions {
+    readonly signal?: AbortSignal;
+}
+/** Anonymous read access, present only on a store whose objects are publicly reachable. */
+export interface PublicObjectAccess {
+    /** The public URL a recipient fetches `key` at. */
+    url(required: {
+        readonly key: string;
+    }): string;
+    /** Anonymous read check: present with `bytes`, or a confirmed 404/410 when `present` is false. Errors are not absence. */
+    verify(required: {
+        readonly key: string;
+        readonly url: string;
+        readonly present: boolean;
+        readonly bytes?: number;
+    }, optional?: ObjectStoreCallOptions): Promise<boolean>;
+}
+export interface ObjectStore {
+    /** `written: false` only when `ifAbsent` was set and the key was already occupied. */
+    put(required: {
+        readonly key: string;
+        readonly bytes: Uint8Array;
+    }, optional?: ObjectStorePutOptions): Promise<{
+        readonly written: boolean;
+    }>;
+    /** `null` only when the key is absent; every other fault rejects. */
+    get(required: {
+        readonly key: string;
+    }, optional?: ObjectStoreCallOptions): Promise<Uint8Array | null>;
+    /** Byte count without reading the payload; `null` only when the key is absent. */
+    head(required: {
+        readonly key: string;
+    }, optional?: ObjectStoreCallOptions): Promise<{
+        readonly size: number;
+    } | null>;
+    /** Idempotent — deleting an absent key is not an error. */
+    delete(required: {
+        readonly key: string;
+    }, optional?: ObjectStoreCallOptions): Promise<void>;
+    readonly publicAccess?: PublicObjectAccess;
+}
+/** What a host hands a provider: non-secret settings, a pre-resolved credential, and its own kit. */
+export interface ObjectStoreCreateInput<H = unknown> {
+    readonly settings: Readonly<Record<string, string | undefined>>;
+    /** Pre-resolved by the host (`fields` non-secret, `secret` the one secret value); never looked up by the provider. */
+    readonly credential?: {
+        readonly fields: Readonly<Record<string, string | undefined>>;
+        readonly secret: string;
+    };
+    /** Host capabilities a plain-JS plugin cannot import (signing, guarded fetch, observability). */
+    readonly host: H;
+}
+export interface ObjectStoreProvider<H = unknown> {
+    create(required: ObjectStoreCreateInput<H>, optional?: Record<string, never>): ProviderResult<ObjectStore>;
+}
+/**
+ * Shape check for a provider value, usable as a registry `validate` or a plugin module `validate`.
+ * @returns The reason it is not a provider, or `undefined`.
+ * @complexity O(1).
+ */
+export declare function objectStoreProviderFault(required: {
+    readonly provider: unknown;
+}): string | undefined;
+/**
+ * A keyed registry for object-store providers whose default is the local filesystem provider.
+ * The `local` provider itself is node-only, so the host registers it (`seed` or `register`).
+ * @complexity O(seed).
+ */
+export declare function createObjectStoreRegistry<H = unknown>(_required?: Record<string, never>, optional?: {
+    readonly seed?: readonly ProviderDefinition<ObjectStoreProvider<H>>[];
+}): ProviderRegistry<ObjectStoreProvider<H>>;
+/**
+ * An `ObjectStore` whose real store is resolved on first use — for hosts whose boot must hand out
+ * a store before the provider choice (a setting, an installed plugin) can be read. A successful
+ * load is kept; a failed load rejects that call and is retried by the next one, so a transient
+ * plugin or settings fault does not pin the store broken for the life of the process.
+ * `publicAccess` is not forwarded: a deferred store cannot know it synchronously.
+ * @complexity O(1) per call after the first successful load.
+ */
+export declare function deferObjectStore(required: {
+    readonly load: () => Promise<ObjectStore>;
+}, _optional?: Record<string, never>): ObjectStore;
+//# sourceMappingURL=object-store.d.ts.map

package/dist/object-store.js

@@ -0,0 +1,70 @@
+/**
+ * @file The ONE object-storage contract (2026-10-21): key → bytes, with an optional public-read
+ * capability. It absorbs four overlapping shapes (cms `BlobStorePort`, capability-providers
+ * `StorageProvider`, devops `ArtifactStorePort`, platform `BlobStorage`); those stay as thin views
+ * over this one until their consumers move. Providers are keyed in a `createProviderRegistry`
+ * (`contract: 'object_store'`), default `local`.
+ *
+ * Universal: types and pure helpers only, so every storage package (all of which already depend
+ * on core) can implement it. Filesystem and network adapters live in node/host packages.
+ *
+ * Data-plane calls REJECT on a storage fault (as every existing byte port did), and report absence
+ * as `null`/`false`, never as a rejection: a caller must never mistake "the store failed" for "the
+ * object is gone". Only `ObjectStoreProvider.create` returns a `ProviderResult`, so a bad or missing
+ * setting is a refusal the host can report, not a boot crash.
+ */
+import { createProviderRegistry } from './provider-registry.js';
+/** Registry contract name for object-store providers. */
+export const OBJECT_STORE_CONTRACT = 'object_store';
+/** The built-in default provider id (local filesystem). */
+export const DEFAULT_OBJECT_STORE_PROVIDER_ID = 'local';
+/**
+ * Shape check for a provider value, usable as a registry `validate` or a plugin module `validate`.
+ * @returns The reason it is not a provider, or `undefined`.
+ * @complexity O(1).
+ */
+export function objectStoreProviderFault(required) {
+    const { provider } = required;
+    if (typeof provider !== 'object' || provider === null)
+        return 'an object-store provider must be an object';
+    return typeof provider.create === 'function' ? undefined : 'an object-store provider must define create()';
+}
+/**
+ * A keyed registry for object-store providers whose default is the local filesystem provider.
+ * The `local` provider itself is node-only, so the host registers it (`seed` or `register`).
+ * @complexity O(seed).
+ */
+export function createObjectStoreRegistry(_required = {}, optional = {}) {
+    return createProviderRegistry({ contract: OBJECT_STORE_CONTRACT }, {
+        defaultProviderId: DEFAULT_OBJECT_STORE_PROVIDER_ID,
+        validate: objectStoreProviderFault,
+        ...(optional.seed === undefined ? {} : { seed: optional.seed }),
+    });
+}
+/**
+ * An `ObjectStore` whose real store is resolved on first use — for hosts whose boot must hand out
+ * a store before the provider choice (a setting, an installed plugin) can be read. A successful
+ * load is kept; a failed load rejects that call and is retried by the next one, so a transient
+ * plugin or settings fault does not pin the store broken for the life of the process.
+ * `publicAccess` is not forwarded: a deferred store cannot know it synchronously.
+ * @complexity O(1) per call after the first successful load.
+ */
+export function deferObjectStore(required, _optional = {}) {
+    let loaded;
+    const current = () => {
+        if (!loaded) {
+            const pending = required.load();
+            loaded = pending;
+            pending.catch(() => { if (loaded === pending)
+                loaded = undefined; });
+        }
+        return loaded;
+    };
+    return {
+        put: async (input, options) => (await current()).put(input, options),
+        get: async (input, options) => (await current()).get(input, options),
+        head: async (input, options) => (await current()).head(input, options),
+        delete: async (input, options) => (await current()).delete(input, options),
+    };
+}
+//# sourceMappingURL=object-store.js.map

package/dist/origin-validation.js

@@ -26,18 +26,23 @@ function splitAllowedOriginsEnv(config, env) {
         .map((origin) => origin.trim())
         .filter(Boolean);
 }
-/** Normalizes one entry to a protocol://host origin; invalid or non-HTTP(S) entries are rejected. */
-function parseAllowedOrigin(entry) {
+/** Parses `value` as a URL, or `undefined` when it is unparseable or not HTTP(S). Shared by
+ * allow-list parsing and the Origin check so both agree on what counts as a web origin. */
+function parseHttpUrl(value) {
     let parsed;
     try {
-        parsed = new URL(entry);
+        parsed = new URL(value);
     }
     catch {
         return undefined;
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
         return undefined;
-    return parsed.origin;
+    return parsed;
+}
+/** Normalizes one entry to a protocol://host origin; invalid or non-HTTP(S) entries are rejected. */
+function parseAllowedOrigin(entry) {
+    return parseHttpUrl(entry)?.origin;
 }
 /**
  * Parses {@link OriginValidationEnvConfig.allowedOriginsEnvVar} into normalized origins.
@@ -93,6 +98,8 @@ export function allowedBrowserPorts({ config, port, env }) {
         ports.push(webPort);
     return ports;
 }
+/** The loopback spellings a locally-served page's Host or Origin can carry. */
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '[::1]'];
 function headerValue(value) {
     if (Array.isArray(value)) {
         const first = value[0];
@@ -113,20 +120,28 @@ export function parseHostHeader({ value }) {
         return null;
     }
 }
+/** Parses an exact dotted-quad (four all-digit parts, each 0-255) into octets, else `undefined`.
+ * Shared by the private-range and IP-literal checks so both agree on what an IPv4 literal is.
+ * `/^\d+$/` admits only non-negative integers, so the octet range check needs only an upper bound. */
+function parseDottedQuad(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    if (!parts.every((part) => /^\d+$/.test(part)))
+        return undefined;
+    const octets = parts.map(Number);
+    return octets.every((n) => n <= 255) ? octets : undefined;
+}
+/** RFC 1918 (10/8, 172.16/12, 192.168/16) or link-local (169.254/16), from the first two octets. */
+function isPrivateIpv4Prefix([a, b]) {
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+}
 /** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16).
  * Implements the dev-browser LAN allow-list, not SSRF blocking. Use @jini-ai/platform/net
  * for SSRF address classification; private addresses are allowed here for local development. */
 export function isPrivateIpv4({ hostname }) {
-    const parts = String(hostname || '').split('.');
-    if (parts.length !== 4)
-        return false;
-    if (!parts.every((part) => /^\d+$/.test(part)))
-        return false;
-    const octets = parts.map((part) => Number(part));
-    if (!octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255))
-        return false;
-    const [a, b] = octets;
-    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    const octets = parseDottedQuad(String(hostname || ''));
+    return octets !== undefined && isPrivateIpv4Prefix(octets);
 }
 /** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
 export function isIpLiteralHostname({ hostname }) {
@@ -135,12 +150,7 @@ export function isIpLiteralHostname({ hostname }) {
         return false;
     if (host.startsWith('[') && host.endsWith(']'))
         return true;
-    const parts = host.split('.');
-    if (parts.length !== 4)
-        return false;
-    if (!parts.every((part) => /^\d+$/.test(part)))
-        return false;
-    return parts.map(Number).every((n) => Number.isInteger(n) && n >= 0 && n <= 255);
+    return parseDottedQuad(host) !== undefined;
 }
 /** Whether `hostname` is loopback, unspecified, or a private-LAN address.
  * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
@@ -159,9 +169,8 @@ export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowed
     const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
-    const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
     const explicitHosts = new Set([
-        ...ports.flatMap((p) => [...loopbackHosts.map((h) => `${h}:${p}`), `${bindHost}:${p}`]),
+        ...ports.flatMap((p) => [...LOOPBACK_HOSTS.map((h) => `${h}:${p}`), `${bindHost}:${p}`]),
         ...configuredAllowedHosts({ origins: extraAllowedOrigins }),
     ]);
     if (explicitHosts.has(requestHost.host))
@@ -170,37 +179,51 @@ export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowed
         return false;
     return isLoopbackOrPrivateLanHost({ hostname: requestHost.hostname });
 }
+/** Every `scheme://host:port` origin a locally-served page can have: loopback spellings and the bind host, over both schemes. */
+function explicitLocalOrigins(ports, bindHost) {
+    const hosts = [...LOOPBACK_HOSTS, bindHost];
+    return new Set(ports.flatMap((p) => ['http', 'https'].flatMap((s) => hosts.map((h) => `${s}://${h}:${p}`))));
+}
+/** The URL's port, or its scheme's default when the URL omits it (only http/https reach here). */
+function effectivePort(url) {
+    return url.port || (url.protocol === 'https:' ? '443' : '80');
+}
 /** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
 export function isAllowedBrowserOrigin({ origin, hostHeader, ports, bindHost, extraAllowedOrigins }) {
-    if (extraAllowedOrigins.includes(String(origin)))
+    const originText = String(origin);
+    if (extraAllowedOrigins.includes(originText))
         return true;
-    let parsedOrigin;
-    try {
-        parsedOrigin = new URL(String(origin));
-    }
-    catch {
-        return false;
-    }
-    if (parsedOrigin.protocol !== 'http:' && parsedOrigin.protocol !== 'https:')
+    const parsedOrigin = parseHttpUrl(originText);
+    if (!parsedOrigin)
         return false;
     const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
-    const schemes = ['http', 'https'];
-    const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
-    const explicitOrigins = new Set(ports.flatMap((p) => [
-        ...schemes.flatMap((s) => loopbackHosts.map((h) => `${s}://${h}:${p}`)),
-        ...schemes.map((s) => `${s}://${bindHost}:${p}`),
-    ]));
-    if (explicitOrigins.has(String(origin)))
+    if (explicitLocalOrigins(ports, bindHost).has(originText))
         return true;
-    const originPort = parsedOrigin.port || (parsedOrigin.protocol === 'https:' ? '443' : '80');
-    if (!ports.map(String).includes(originPort))
+    if (!ports.map(String).includes(effectivePort(parsedOrigin)))
         return false;
     if (parsedOrigin.hostname !== requestHost.hostname)
         return false;
     return isLoopbackOrPrivateLanHost({ hostname: parsedOrigin.hostname });
 }
+/** The decision for a request carrying no `Origin` header (as a same-origin GET subresource does). */
+function isAllowedWithoutOrigin({ req, hostArgs, extraAllowedOrigins }) {
+    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname({ hostname: new URL(o).hostname }));
+    if (isAllowedBrowserHost({ ...hostArgs, extraAllowedOrigins: ipOnlyExtraOrigins }))
+        return true;
+    // Browsers (Firefox, Chrome) omit Origin on same-origin GET subresource
+    // requests per the Fetch spec, which makes hostname entries in the
+    // allow-list unreachable for legitimate same-origin GETs through a
+    // reverse proxy. Sec-Fetch-Site is set by the user agent and cannot be
+    // modified by JavaScript, so a value of "same-origin" attests that the
+    // request originated from the same origin as the target — a cross-site
+    // `<img>`/`<script>` exploit would carry "cross-site" instead. Only
+    // consult the broader allow-list once that signal is present.
+    if (headerValue(req.headers?.['sec-fetch-site']) !== 'same-origin')
+        return false;
+    return isAllowedBrowserHost({ ...hostArgs, extraAllowedOrigins });
+}
 /**
  * The top-level same-origin gate: is `req` a request the daemon should treat
  * as coming from one of its own locally-served (or explicitly allow-listed)
@@ -212,24 +235,8 @@ export function isLocalSameOrigin({ config, req, port, env }, { logger } = {}) {
     const ports = allowedBrowserPorts({ config, port, env });
     const bindHost = env[config.bindHostEnvVar] || '127.0.0.1';
     const extraAllowedOrigins = configuredAllowedOrigins({ config, env }, { logger });
-    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname({ hostname: new URL(o).hostname }));
-    const localHostAllowed = isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins: ipOnlyExtraOrigins });
     if (origin == null || origin === '') {
-        if (localHostAllowed)
-            return true;
-        // Browsers (Firefox, Chrome) omit Origin on same-origin GET subresource
-        // requests per the Fetch spec, which makes hostname entries in the
-        // allow-list unreachable for legitimate same-origin GETs through a
-        // reverse proxy. Sec-Fetch-Site is set by the user agent and cannot be
-        // modified by JavaScript, so a value of "same-origin" attests that the
-        // request originated from the same origin as the target — a cross-site
-        // `<img>`/`<script>` exploit would carry "cross-site" instead. Only
-        // consult the broader allow-list once that signal is present.
-        const fetchSite = headerValue(req.headers?.['sec-fetch-site']);
-        if (fetchSite === 'same-origin') {
-            return isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins });
-        }
-        return false;
+        return isAllowedWithoutOrigin({ req, hostArgs: { config, hostHeader: host, ports, bindHost }, extraAllowedOrigins });
     }
     // Reverse-proxy deployments terminate the browser connection at the proxy
     // and open a fresh upstream connection to the daemon. The Host header the

package/dist/primitives/http.d.ts

@@ -5,8 +5,8 @@ export type HttpRequest = {
     method: "POST" | "GET" | "HEAD" | "PUT" | "PATCH" | "DELETE";
     url: string;
     headers: Readonly<Record<string, string>>;
-    /** Preserve the signed bytes: re-serialization between signing and sending changes the signature. */
-    body?: string;
+    /** Preserve signed text and raw binary uploads without base64 expansion or UTF-8 corruption. */
+    body?: string | Uint8Array;
     /** Whole-operation deadline, including DNS, redirects and body reads. Off by default.
      * Retry/backoff belongs to the caller; its deadline can cover the whole retry operation. */
     totalDeadlineMs?: number;

package/dist/primitives/index.d.ts

@@ -7,4 +7,5 @@ export type { DecodedSseEvent, DecodedSseFrame, SseFramingOptions } from './sse.
 export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
+export * from './tasks.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.js

@@ -6,4 +6,5 @@ export { decodeSseFrames, decodeSseStream, parseSseRecord } from './sse.js';
 export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
+export * from './tasks.js';
 //# sourceMappingURL=index.js.map