@jini-ai/core 0.3.0 → 0.4.0

package/dist/model-facing-tool-errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Ordered domain-owned allowlists for safe model-facing failures. Unknown throws are unchanged.
+ * Rule evaluation is O(r); container wrapping O(n), with no I/O or reporting dependencies.
+ */
+import { type ToolHandler, type ToolRegistration } from "./tool-registry.js";
+export interface ModelFacingErrorRule {
+    readonly error: abstract new (...args: never[]) => Error;
+    readonly code: string;
+    readonly message?: string;
+    readonly guidance?: string;
+}
+export declare function forbiddenRule(required: {
+    domainPrefix: string;
+    error: ModelFacingErrorRule["error"];
+}): ModelFacingErrorRule;
+export declare function reclassifyToolError(required: {
+    err: unknown;
+    rules: readonly ModelFacingErrorRule[];
+}): unknown;
+export declare function withModelFacingErrors(required: {
+    handlers: Readonly<Record<string, ToolHandler>>;
+    rules: readonly ModelFacingErrorRule[];
+}): Record<string, ToolHandler>;
+export declare function withModelFacingRegistrationErrors(required: {
+    registrations: readonly ToolRegistration[];
+    rules: readonly ModelFacingErrorRule[];
+}): ToolRegistration[];
+export interface CallerSafeErrorRule {
+    readonly error: abstract new (...args: never[]) => Error;
+    readonly message?: string;
+}
+export declare function callerSafeErrorMessage(required: {
+    err: unknown;
+    rules: readonly CallerSafeErrorRule[];
+    fallback: string;
+}): string;
+//# sourceMappingURL=model-facing-tool-errors.d.ts.map

package/dist/model-facing-tool-errors.js

@@ -0,0 +1,71 @@
+/**
+ * Ordered domain-owned allowlists for safe model-facing failures. Unknown throws are unchanged.
+ * Rule evaluation is O(r); container wrapping O(n), with no I/O or reporting dependencies.
+ */
+// Tool transports redact unknown throws as internal failures. Leaving known domain refusals there
+// made validation/not-found/permission errors look like identical crashes, preventing recovery.
+// Domains explicitly own which classes/messages are safe to expose, including anonymous callers:
+// stacks, internal paths, SQL, credentials, and another tenant's data must remain unlisted/redacted.
+import { ToolInputError } from "./tool-registry.js";
+export function forbiddenRule(required) {
+    return { error: required.error, code: `${required.domainPrefix}_FORBIDDEN` };
+}
+// First match wins: list subclasses before superclasses. Unmatched values must retain identity so
+// the transport's redaction remains the default; already-classified ToolInputError also stays intact
+// to avoid doubling a prefix attached by schema/recovery wrapping.
+export function reclassifyToolError(required) {
+    const { err, rules } = required;
+    if (err instanceof ToolInputError)
+        return err;
+    for (const rule of rules) {
+        if (err instanceof rule.error) {
+            const message = `${rule.code}: ${rule.message ?? err.message}`;
+            return new ToolInputError({ message: rule.guidance ? `${message}. ${rule.guidance}` : message });
+        }
+    }
+    return err;
+}
+// Wrap the whole map once: a correct per-handler converter previously reached only one handler
+// while sibling operations still leaked into the internal-error redactor. Central wrapping has no
+// omitted call-site arm, and successful results pass through untouched.
+export function withModelFacingErrors(required) {
+    const { handlers, rules } = required;
+    return Object.fromEntries(Object.entries(handlers).map(([toolId, handler]) => [
+        toolId,
+        async (ctx, optional = {}) => {
+            try {
+                return await handler(ctx, optional);
+            }
+            catch (err) {
+                throw reclassifyToolError({ err, rules });
+            }
+        },
+    ]));
+}
+// Registration-array builders need the same blanket coverage as handler maps. Preserve descriptor,
+// policy, ordering, and successful results; only the rejection path is reclassified.
+export function withModelFacingRegistrationErrors(required) {
+    const { registrations, rules } = required;
+    return registrations.map((registration) => ({
+        ...registration,
+        handler: (async (ctx, optional = {}) => {
+            try {
+                return await registration.handler(ctx, optional);
+            }
+            catch (err) {
+                throw reclassifyToolError({ err, rules });
+            }
+        }),
+    }));
+}
+// Unknown classes, raw driver errors, and non-Error throws get fixed fallback text, never raw error
+// content. The fallback itself must not be derived from err; first matching rule still wins.
+export function callerSafeErrorMessage(required) {
+    const { err, rules, fallback } = required;
+    for (const rule of rules) {
+        if (err instanceof rule.error)
+            return rule.message ?? err.message;
+    }
+    return fallback;
+}
+//# sourceMappingURL=model-facing-tool-errors.js.map

package/dist/naming.d.ts

@@ -0,0 +1,31 @@
+/** Bounded asynchronous collision search; naming and copy wording are required host policy. */
+export declare const MAX_SUFFIX_ATTEMPTS = 1000;
+export interface NamingPolicy {
+    isTaken: (required: {
+        candidate: string;
+    }) => Promise<boolean>;
+    withSuffix: (required: {
+        base: string;
+        suffix: number;
+    }) => string;
+    exhaustionMessage: (required: {
+        base: string;
+        maxAttempts: number;
+    }) => string;
+}
+export interface AvailableNameOptions {
+    maxAttempts?: number;
+    onExhausted?: (required: {
+        base: string;
+        maxAttempts: number;
+    }) => never;
+}
+/** O(k) sequential predicate calls, O(1) local space, k <= maxAttempts. */
+export declare function deriveAvailableName(required: NamingPolicy & {
+    base: string;
+}, optional?: AvailableNameOptions): Promise<string>;
+/** O(k) plus at most one base lookup. A trailing integer is a counter only if its base exists. */
+export declare function deriveDuplicateName(required: NamingPolicy & {
+    sourceName: string;
+}, optional?: AvailableNameOptions): Promise<string>;
+//# sourceMappingURL=naming.d.ts.map

package/dist/naming.js

@@ -0,0 +1,33 @@
+/** Bounded asynchronous collision search; naming and copy wording are required host policy. */
+export const MAX_SUFFIX_ATTEMPTS = 1000;
+/** O(k) sequential predicate calls, O(1) local space, k <= maxAttempts. */
+export async function deriveAvailableName(required, optional = {}) {
+    // isTaken may also reject reserved/invalid candidates. withSuffix owns formatting and length caps;
+    // shorten the base to make room rather than truncating the counter and repeating a taken candidate.
+    const maxAttempts = optional.maxAttempts ?? MAX_SUFFIX_ATTEMPTS;
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1)
+        throw new RangeError('maxAttempts must be a positive safe integer');
+    for (let suffix = 1; suffix <= maxAttempts; suffix += 1) {
+        const candidate = suffix === 1 ? required.base : required.withSuffix({ base: required.base, suffix });
+        if (!(await required.isTaken({ candidate })))
+            return candidate;
+    }
+    if (optional.onExhausted)
+        optional.onExhausted({ base: required.base, maxAttempts });
+    throw new Error(required.exhaustionMessage({ base: required.base, maxAttempts }));
+}
+const TRAILING_NUMBER_PATTERN = /^(.*\S) \d+$/;
+// Require a non-space base: a bare number has nothing meaningful to strip. Existing-base evidence
+// distinguishes a copy counter ("Landing 2") from a real title ("Blog 2024" with no "Blog" row).
+/** O(k) plus at most one base lookup. A trailing integer is a counter only if its base exists. */
+export async function deriveDuplicateName(required, optional = {}) {
+    const strippedBase = TRAILING_NUMBER_PATTERN.exec(required.sourceName)?.[1];
+    const base = strippedBase !== undefined && await required.isTaken({ candidate: strippedBase })
+        ? strippedBase : required.sourceName;
+    return deriveAvailableName({
+        // A copy must never reuse the source's name, even if the external predicate overlooks its row.
+        ...required, base,
+        isTaken: ({ candidate }) => candidate === required.sourceName ? Promise.resolve(true) : required.isTaken({ candidate }),
+    }, optional);
+}
+//# sourceMappingURL=naming.js.map

package/dist/origin-validation.d.ts

@@ -9,12 +9,13 @@
  *
  * Generalized from an upstream flat daemon module: the origin hardcoded its
  * host product's env-var names, now fields on
- * {@link OriginValidationEnvConfig} — see `source-map.md` for the exact
+ * {@link OriginValidationEnvConfig} — see `archived provenance ledger` for the exact
  * mapping. One function, a bypass for a specific product's own
  * browser-extension-driven ingest route, was deliberately **not** ported —
  * it names a specific product route and product feature with no generic
- * equivalent; see `source-map.md`.
+ * equivalent; see `archived provenance ledger`.
  */
+import type { Logger } from "./primitives/index.js";
 export interface ParsedHostHeader {
     hostname: string;
     host: string;
@@ -36,44 +37,88 @@ export interface OriginValidationEnvConfig {
     /** Env var carrying the host the daemon itself is bound to (default `'127.0.0.1'`). */
     bindHostEnvVar: string;
 }
+/** Host-supplied environment snapshot, shared by origin validation helpers. */
+export interface OriginValidationArgs {
+    config: OriginValidationEnvConfig;
+    env: Readonly<Record<string, string | undefined>>;
+}
+/** Optional diagnostic sink; validation never reads an ambient logger. */
+export type OriginValidationLoggerPort = Pick<Logger, "warn">;
 /**
  * Parses {@link OriginValidationEnvConfig.allowedOriginsEnvVar} into normalized origins.
  *
  * Deliberately never throws — this is on the hot path of {@link isLocalSameOrigin}, called fresh
  * on every same-origin decision a host makes. A malformed entry is dropped and logged instead of
- * aborting the whole parse (see the twin `@jini-ai/http-kit` copy of this module for the fuller
- * incident history this mirrors: a request-time throw here used to turn one config typo into
+ * aborting the whole parse. A request-time throw used to turn one config typo into
  * either a 500 on every request, or — on a route with no enclosing catch — an unhandled
- * rejection). Call {@link assertValidAllowedOrigins} once at host startup instead, to fail loudly
+ * rejection: hand-mounted attachment routes and provider catch-all routes had no common
+ * enclosing catch. Dropping the malformed entry degrades to one fewer trusted origin,
+ * never every request breaking. Call {@link assertValidAllowedOrigins} once at host startup instead, to fail loudly
  * before any request-serving traffic exists.
  */
-export declare function configuredAllowedOrigins(config: OriginValidationEnvConfig, env?: NodeJS.ProcessEnv): string[];
+export declare function configuredAllowedOrigins({ config, env }: OriginValidationArgs, { logger }?: {
+    logger?: OriginValidationLoggerPort | undefined;
+}): string[];
 /**
  * Boot-time companion to {@link configuredAllowedOrigins}: throws, naming every malformed entry,
  * instead of silently dropping them. Call once, early in host startup, before the HTTP server
- * accepts connections.
+ * accepts connections. A misconfiguration must fail boot loudly rather than quietly serving with
+ * a smaller-than-intended allow-list, or throwing on whichever request first reaches the guard.
  */
-export declare function assertValidAllowedOrigins(config: OriginValidationEnvConfig, env?: NodeJS.ProcessEnv): void;
+export declare function assertValidAllowedOrigins({ config, env }: OriginValidationArgs): void;
 /** The `host` (hostname:port) component of each configured allowed origin. */
-export declare function configuredAllowedHosts(origins: string[]): string[];
+export declare function configuredAllowedHosts({ origins }: {
+    origins: string[];
+}): string[];
 /** The set of browser-facing ports considered "local": the daemon's own port plus an optional configured web port. */
-export declare function allowedBrowserPorts(config: OriginValidationEnvConfig, port: number | string | null | undefined, env?: NodeJS.ProcessEnv): number[];
+export declare function allowedBrowserPorts({ config, port, env }: OriginValidationArgs & {
+    port: number | string | null | undefined;
+}): number[];
 /** Parses a raw `Host` header value into hostname/host/port, or `null` when unparseable. */
-export declare function parseHostHeader(value: unknown): ParsedHostHeader | null;
-/** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16). */
-export declare function isPrivateIpv4(hostname: unknown): boolean;
+export declare function parseHostHeader({ value }: {
+    value: unknown;
+}): ParsedHostHeader | null;
+/** 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 declare function isPrivateIpv4({ hostname }: {
+    hostname: unknown;
+}): boolean;
 /** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
-export declare function isIpLiteralHostname(hostname: unknown): boolean;
-/** Whether `hostname` is loopback, unspecified, or a private-LAN address. */
-export declare function isLoopbackOrPrivateLanHost(hostname: unknown): boolean;
+export declare function isIpLiteralHostname({ hostname }: {
+    hostname: unknown;
+}): boolean;
+/** Whether `hostname` is loopback, unspecified, or a private-LAN address.
+ * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
+export declare function isLoopbackOrPrivateLanHost({ hostname }: {
+    hostname: unknown;
+}): boolean;
 /** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
-export declare function isAllowedBrowserHost(config: OriginValidationEnvConfig, hostHeader: unknown, ports: number[], bindHost: string, extraAllowedOrigins: string[]): boolean;
+export declare function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowedOrigins }: {
+    config: OriginValidationEnvConfig;
+    hostHeader: unknown;
+    ports: number[];
+    bindHost: string;
+    extraAllowedOrigins: string[];
+}): boolean;
 /** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
-export declare function isAllowedBrowserOrigin(config: OriginValidationEnvConfig, origin: unknown, hostHeader: unknown, ports: number[], bindHost: string, extraAllowedOrigins: string[]): boolean;
+export declare function isAllowedBrowserOrigin({ origin, hostHeader, ports, bindHost, extraAllowedOrigins }: {
+    config: OriginValidationEnvConfig;
+    origin: unknown;
+    hostHeader: unknown;
+    ports: number[];
+    bindHost: string;
+    extraAllowedOrigins: string[];
+}): boolean;
 /**
  * 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)
  * pages.
  */
-export declare function isLocalSameOrigin(config: OriginValidationEnvConfig, req: RequestWithOriginHeaders, port: number | string | null | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function isLocalSameOrigin({ config, req, port, env }: OriginValidationArgs & {
+    req: RequestWithOriginHeaders;
+    port: number | string | null | undefined;
+}, { logger }?: {
+    logger?: OriginValidationLoggerPort | undefined;
+}): boolean;
 //# sourceMappingURL=origin-validation.d.ts.map

package/dist/origin-validation.js

@@ -9,12 +9,14 @@
  *
  * Generalized from an upstream flat daemon module: the origin hardcoded its
  * host product's env-var names, now fields on
- * {@link OriginValidationEnvConfig} — see `source-map.md` for the exact
+ * {@link OriginValidationEnvConfig} — see `archived provenance ledger` for the exact
  * mapping. One function, a bypass for a specific product's own
  * browser-extension-driven ingest route, was deliberately **not** ported —
  * it names a specific product route and product feature with no generic
- * equivalent; see `source-map.md`.
+ * equivalent; see `archived provenance ledger`.
  */
+/** Splits and trims the configured allow-list into entries. Both lenient request parsing and
+ * strict boot validation share this splitter so their definition of one entry cannot drift. */
 function splitAllowedOriginsEnv(config, env) {
     const raw = env[config.allowedOriginsEnvVar] || '';
     if (!raw.trim())
@@ -24,6 +26,7 @@ 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) {
     let parsed;
     try {
@@ -41,18 +44,21 @@ function parseAllowedOrigin(entry) {
  *
  * Deliberately never throws — this is on the hot path of {@link isLocalSameOrigin}, called fresh
  * on every same-origin decision a host makes. A malformed entry is dropped and logged instead of
- * aborting the whole parse (see the twin `@jini-ai/http-kit` copy of this module for the fuller
- * incident history this mirrors: a request-time throw here used to turn one config typo into
+ * aborting the whole parse. A request-time throw used to turn one config typo into
  * either a 500 on every request, or — on a route with no enclosing catch — an unhandled
- * rejection). Call {@link assertValidAllowedOrigins} once at host startup instead, to fail loudly
+ * rejection: hand-mounted attachment routes and provider catch-all routes had no common
+ * enclosing catch. Dropping the malformed entry degrades to one fewer trusted origin,
+ * never every request breaking. Call {@link assertValidAllowedOrigins} once at host startup instead, to fail loudly
  * before any request-serving traffic exists.
  */
-export function configuredAllowedOrigins(config, env = process.env) {
+export function configuredAllowedOrigins({ config, env }, { logger } = {}) {
     const origins = [];
     for (const entry of splitAllowedOriginsEnv(config, env)) {
         const origin = parseAllowedOrigin(entry);
         if (origin === undefined) {
-            console.warn(`[@jini-ai/core] ignoring malformed ${config.allowedOriginsEnvVar} entry (must be an http:// or https:// origin): ${entry}`);
+            logger?.warn({
+                message: `[@jini-ai/core] ignoring malformed ${config.allowedOriginsEnvVar} entry (must be an http:// or https:// origin): ${entry}`,
+            });
             continue;
         }
         origins.push(origin);
@@ -62,9 +68,10 @@ export function configuredAllowedOrigins(config, env = process.env) {
 /**
  * Boot-time companion to {@link configuredAllowedOrigins}: throws, naming every malformed entry,
  * instead of silently dropping them. Call once, early in host startup, before the HTTP server
- * accepts connections.
+ * accepts connections. A misconfiguration must fail boot loudly rather than quietly serving with
+ * a smaller-than-intended allow-list, or throwing on whichever request first reaches the guard.
  */
-export function assertValidAllowedOrigins(config, env = process.env) {
+export function assertValidAllowedOrigins({ config, env }) {
     const invalid = splitAllowedOriginsEnv(config, env).filter((entry) => parseAllowedOrigin(entry) === undefined);
     if (invalid.length === 0)
         return;
@@ -72,11 +79,11 @@ export function assertValidAllowedOrigins(config, env = process.env) {
         `(must be http:// or https:// origins): ${invalid.join(', ')}`);
 }
 /** The `host` (hostname:port) component of each configured allowed origin. */
-export function configuredAllowedHosts(origins) {
+export function configuredAllowedHosts({ origins }) {
     return origins.map((origin) => new URL(origin).host);
 }
 /** The set of browser-facing ports considered "local": the daemon's own port plus an optional configured web port. */
-export function allowedBrowserPorts(config, port, env = process.env) {
+export function allowedBrowserPorts({ config, port, env }) {
     const ports = [];
     const primary = Number(port);
     if (primary)
@@ -94,7 +101,7 @@ function headerValue(value) {
     return value == null ? undefined : String(value);
 }
 /** Parses a raw `Host` header value into hostname/host/port, or `null` when unparseable. */
-export function parseHostHeader(value) {
+export function parseHostHeader({ value }) {
     const raw = String(headerValue(value) || '').trim();
     if (!raw)
         return null;
@@ -106,8 +113,10 @@ export function parseHostHeader(value) {
         return null;
     }
 }
-/** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16). */
-export function isPrivateIpv4(hostname) {
+/** 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;
@@ -120,7 +129,7 @@ export function isPrivateIpv4(hostname) {
     return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
 }
 /** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
-export function isIpLiteralHostname(hostname) {
+export function isIpLiteralHostname({ hostname }) {
     const host = String(hostname || '').trim();
     if (!host)
         return false;
@@ -133,8 +142,9 @@ export function isIpLiteralHostname(hostname) {
         return false;
     return parts.map(Number).every((n) => Number.isInteger(n) && n >= 0 && n <= 255);
 }
-/** Whether `hostname` is loopback, unspecified, or a private-LAN address. */
-export function isLoopbackOrPrivateLanHost(hostname) {
+/** Whether `hostname` is loopback, unspecified, or a private-LAN address.
+ * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
+export function isLoopbackOrPrivateLanHost({ hostname }) {
     const host = String(hostname || '').toLowerCase();
     return (host === 'localhost' ||
         host === '127.0.0.1' ||
@@ -142,26 +152,26 @@ export function isLoopbackOrPrivateLanHost(hostname) {
         host === '[::1]' ||
         host === '0.0.0.0' ||
         host === '::' ||
-        isPrivateIpv4(host));
+        isPrivateIpv4({ hostname: host }));
 }
 /** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
-export function isAllowedBrowserHost(config, hostHeader, ports, bindHost, extraAllowedOrigins) {
-    const requestHost = parseHostHeader(hostHeader);
+export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowedOrigins }) {
+    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}`]),
-        ...configuredAllowedHosts(extraAllowedOrigins),
+        ...configuredAllowedHosts({ origins: extraAllowedOrigins }),
     ]);
     if (explicitHosts.has(requestHost.host))
         return true;
     if (!ports.map(String).includes(requestHost.port))
         return false;
-    return isLoopbackOrPrivateLanHost(requestHost.hostname);
+    return isLoopbackOrPrivateLanHost({ hostname: requestHost.hostname });
 }
 /** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
-export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHost, extraAllowedOrigins) {
+export function isAllowedBrowserOrigin({ origin, hostHeader, ports, bindHost, extraAllowedOrigins }) {
     if (extraAllowedOrigins.includes(String(origin)))
         return true;
     let parsedOrigin;
@@ -173,7 +183,7 @@ export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHo
     }
     if (parsedOrigin.protocol !== 'http:' && parsedOrigin.protocol !== 'https:')
         return false;
-    const requestHost = parseHostHeader(hostHeader);
+    const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
     const schemes = ['http', 'https'];
@@ -189,21 +199,21 @@ export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHo
         return false;
     if (parsedOrigin.hostname !== requestHost.hostname)
         return false;
-    return isLoopbackOrPrivateLanHost(parsedOrigin.hostname);
+    return isLoopbackOrPrivateLanHost({ hostname: parsedOrigin.hostname });
 }
 /**
  * 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)
  * pages.
  */
-export function isLocalSameOrigin(config, req, port, env = process.env) {
+export function isLocalSameOrigin({ config, req, port, env }, { logger } = {}) {
     const host = String(headerValue(req.headers?.host) || '');
     const origin = headerValue(req.headers?.origin);
-    const ports = allowedBrowserPorts(config, port, env);
+    const ports = allowedBrowserPorts({ config, port, env });
     const bindHost = env[config.bindHostEnvVar] || '127.0.0.1';
-    const extraAllowedOrigins = configuredAllowedOrigins(config, env);
-    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname(new URL(o).hostname));
-    const localHostAllowed = isAllowedBrowserHost(config, host, ports, bindHost, ipOnlyExtraOrigins);
+    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;
@@ -217,7 +227,7 @@ export function isLocalSameOrigin(config, req, port, env = process.env) {
         // 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, host, ports, bindHost, extraAllowedOrigins);
+            return isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins });
         }
         return false;
     }
@@ -230,8 +240,8 @@ export function isLocalSameOrigin(config, req, port, env = process.env) {
     // allow-listed entry is the documented escape hatch for these deployments.
     if (extraAllowedOrigins.includes(origin))
         return true;
-    if (!isAllowedBrowserHost(config, host, ports, bindHost, extraAllowedOrigins))
+    if (!isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins }))
         return false;
-    return isAllowedBrowserOrigin(config, origin, host, ports, bindHost, extraAllowedOrigins);
+    return isAllowedBrowserOrigin({ config, origin, hostHeader: host, ports, bindHost, extraAllowedOrigins });
 }
 //# sourceMappingURL=origin-validation.js.map

package/dist/pack-lifecycle.d.ts

@@ -15,17 +15,17 @@ import type { Pack } from './pack.js';
 import type { ToolRegistration, ToolRegistry } from './tool-registry.js';
 type AnyPack = Pack<any, any, string>;
 /**
- * Registers `pack.tools(services)` for every pack in `packs` that declares one, in pack order,
+ * Registers `pack.tools({ services })` for every pack in `packs` that declares one, in pack order,
  * into the single shared `registry`.
  *
  * Order matters and is deliberately the caller's to choose: `ToolRegistry.register` throws on a
- * duplicate descriptor id, so whichever pack registers second is the one named in the error. A
- * composition root that wants a host's own tools to win that message registers the host's packs
- * last.
+ * duplicate descriptor id, so whichever pack registers second triggers the error. The registry
+ * message names only the tool ID, not either pack. A composition root that wants a host's own
+ * contribution to trigger the duplicate failure registers the host's packs last.
  *
- * @param registry - The shared registry every composed pack contributes into.
- * @param packs - The composed packs, in composition order.
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.registry - The shared registry every composed pack contributes into.
+ * @param required.packs - The composed packs, in composition order.
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns Every registration that was added, in the order it was added — so a caller can seed a
  * catalog, log an inventory, or assert on the composition without re-deriving it.
  * @throws Whatever `ToolRegistry.register` throws (notably a duplicate descriptor id), at the
@@ -33,14 +33,18 @@ type AnyPack = Pack<any, any, string>;
  * registered tool set is not a state anything downstream can reason about.
  * @complexity O(t) in total contributed tools.
  */
-export declare function registerPackTools<const Packs extends readonly AnyPack[]>(registry: ToolRegistry, packs: Packs, daemon: Daemon<Packs>): readonly ToolRegistration[];
+export declare function registerPackTools<const Packs extends readonly AnyPack[]>({ registry, packs, daemon }: {
+    registry: ToolRegistry;
+    packs: Packs;
+    daemon: Daemon<Packs>;
+}): readonly ToolRegistration[];
 /** One pack's teardown failure, kept with the pack's name so a caller can report which one failed. */
 export interface PackDisposalFailure {
     readonly pack: string;
     readonly error: unknown;
 }
 /**
- * Runs `pack.dispose(services)` for every pack that declares one, in **reverse** composition order
+ * Runs `pack.dispose({ services })` for every pack that declares one, in **reverse** composition order
  * (a pack composed later may depend on an earlier pack's resources, so it must release first).
  *
  * Best-effort by design: one pack throwing must never prevent the rest from disposing, or a single
@@ -48,11 +52,14 @@ export interface PackDisposalFailure {
  * and returned rather than thrown, leaving the composition root free to decide whether a teardown
  * failure is worth surfacing to its own caller.
  *
- * @param packs - The composed packs, in composition order (this function reverses them itself).
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.packs - The composed packs, in composition order (this function reverses them itself).
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns The failures, in the order they occurred. Empty when every pack disposed cleanly.
  * @complexity O(p) in pack count, plus each pack's own teardown cost.
  */
-export declare function disposePacks<const Packs extends readonly AnyPack[]>(packs: Packs, daemon: Daemon<Packs>): Promise<readonly PackDisposalFailure[]>;
+export declare function disposePacks<const Packs extends readonly AnyPack[]>({ packs, daemon }: {
+    packs: Packs;
+    daemon: Daemon<Packs>;
+}): Promise<readonly PackDisposalFailure[]>;
 export {};
 //# sourceMappingURL=pack-lifecycle.d.ts.map

package/dist/pack-lifecycle.js

@@ -1,15 +1,15 @@
 /**
- * Registers `pack.tools(services)` for every pack in `packs` that declares one, in pack order,
+ * Registers `pack.tools({ services })` for every pack in `packs` that declares one, in pack order,
  * into the single shared `registry`.
  *
  * Order matters and is deliberately the caller's to choose: `ToolRegistry.register` throws on a
- * duplicate descriptor id, so whichever pack registers second is the one named in the error. A
- * composition root that wants a host's own tools to win that message registers the host's packs
- * last.
+ * duplicate descriptor id, so whichever pack registers second triggers the error. The registry
+ * message names only the tool ID, not either pack. A composition root that wants a host's own
+ * contribution to trigger the duplicate failure registers the host's packs last.
  *
- * @param registry - The shared registry every composed pack contributes into.
- * @param packs - The composed packs, in composition order.
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.registry - The shared registry every composed pack contributes into.
+ * @param required.packs - The composed packs, in composition order.
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns Every registration that was added, in the order it was added — so a caller can seed a
  * catalog, log an inventory, or assert on the composition without re-deriving it.
  * @throws Whatever `ToolRegistry.register` throws (notably a duplicate descriptor id), at the
@@ -17,11 +17,11 @@
  * registered tool set is not a state anything downstream can reason about.
  * @complexity O(t) in total contributed tools.
  */
-export function registerPackTools(registry, packs, daemon) {
+export function registerPackTools({ registry, packs, daemon }) {
     const services = daemon.services;
     const registered = [];
     for (const pack of packs) {
-        for (const registration of pack.tools?.(services[pack.name]) ?? []) {
+        for (const registration of pack.tools?.({ services: services[pack.name] }) ?? []) {
             registry.register(registration);
             registered.push(registration);
         }
@@ -29,7 +29,7 @@ export function registerPackTools(registry, packs, daemon) {
     return registered;
 }
 /**
- * Runs `pack.dispose(services)` for every pack that declares one, in **reverse** composition order
+ * Runs `pack.dispose({ services })` for every pack that declares one, in **reverse** composition order
  * (a pack composed later may depend on an earlier pack's resources, so it must release first).
  *
  * Best-effort by design: one pack throwing must never prevent the rest from disposing, or a single
@@ -37,12 +37,12 @@ export function registerPackTools(registry, packs, daemon) {
  * and returned rather than thrown, leaving the composition root free to decide whether a teardown
  * failure is worth surfacing to its own caller.
  *
- * @param packs - The composed packs, in composition order (this function reverses them itself).
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.packs - The composed packs, in composition order (this function reverses them itself).
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns The failures, in the order they occurred. Empty when every pack disposed cleanly.
  * @complexity O(p) in pack count, plus each pack's own teardown cost.
  */
-export async function disposePacks(packs, daemon) {
+export async function disposePacks({ packs, daemon }) {
     const services = daemon.services;
     const failures = [];
     for (let index = packs.length - 1; index >= 0; index -= 1) {
@@ -50,7 +50,7 @@ export async function disposePacks(packs, daemon) {
         if (!pack.dispose)
             continue;
         try {
-            await pack.dispose(services[pack.name]);
+            await pack.dispose({ services: services[pack.name] });
         }
         catch (error) {
             failures.push({ pack: pack.name, error });