@jini-ai/http-kit 0.3.7 → 0.3.8

package/dist/delegated-tools.d.ts

@@ -36,6 +36,13 @@ export interface DelegatedToolsInternalErrorContext {
     readonly toolId: string;
     readonly correlationId: string;
     readonly error: unknown;
+    /**
+     * The settled status when the failure is a `ToolExecutionResult` this route will not show as-is
+     * (`timed-out`, `cancelled`, or a `failed` the host did not mark model-safe); absent when `error`
+     * is a thrown exception. Lets a host word a timeout differently from a crash without parsing
+     * `error`, which for a settled result is only `result.error ?? result.status`.
+     */
+    readonly status?: 'timed-out' | 'cancelled' | 'failed';
 }
 export interface DelegatedToolsHttpDeps {
     readonly lifecycle: RunLifecycle;
@@ -67,6 +74,21 @@ export interface DelegatedToolsHttpDeps {
      * redaction of its own on this path.
      */
     readonly isModelSafeToolFailure?: (result: ToolExecutionResult) => boolean;
+    /**
+     * Host opt-in: the model-safe text to send in place of `'an internal error occurred'` for every
+     * failure this route would otherwise answer with the SEC-005-redacted `500 INTERNAL_ERROR` — a
+     * thrown executor (e.g. an unknown tool id), a throwing `resolvePrincipal`, `timed-out`,
+     * `cancelled`, and a `failed` result `isModelSafeToolFailure` did not vouch for. Without it, those
+     * reach the model as a bare "INTERNAL_ERROR" it can neither act on nor report.
+     *
+     * The response keeps `500 INTERNAL_ERROR` and its `requestId`; only `message` changes, and
+     * `onInternalError` still receives the raw failure first. Returning `undefined` or `''` keeps the
+     * generic message for that failure, and so does a describer that throws — a broken describer can
+     * never turn a 500 into a leak or a crash. Omitted (the default), nothing changes. The host owns
+     * redaction here exactly as for `isModelSafeToolFailure`: this route sends the returned text
+     * verbatim.
+     */
+    readonly describeInternalError?: (context: DelegatedToolsInternalErrorContext) => string | undefined;
 }
 /**
  * Refusal text for a `requireReadOnly` call naming a tool that is not registered read-only —

package/dist/delegated-tools.js

@@ -168,11 +168,39 @@ function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
     console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
 }
-function reportInternalError(deps, source, error, runId, toolId) {
+/**
+ * The host's {@link DelegatedToolsHttpDeps.describeInternalError} text for `context`, or `undefined`
+ * when there is no describer, it declines (`undefined`/`''`), or it throws.
+ *
+ * @complexity O(1) plus the describer's own cost.
+ */
+function describeSafely(deps, context) {
+    if (deps.describeInternalError === undefined)
+        return undefined;
+    try {
+        const text = deps.describeInternalError(context);
+        return typeof text === 'string' && text.length > 0 ? text : undefined;
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`[@jini-ai/http-kit] describeInternalError threw (correlationId=${context.correlationId})`, error);
+        return undefined;
+    }
+}
+function reportInternalError(deps, source, error, runId, toolId, status) {
     const correlationId = randomUUID();
+    const context = {
+        source,
+        runId,
+        toolId,
+        correlationId,
+        error,
+        ...(status === undefined ? {} : { status }),
+    };
     const sink = deps.onInternalError ?? defaultInternalErrorSink;
-    sink({ source, runId, toolId, correlationId, error });
-    return createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId });
+    sink(context);
+    const message = describeSafely(deps, context) ?? 'an internal error occurred';
+    return createApiError('INTERNAL_ERROR', message, { requestId: correlationId });
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -212,7 +240,8 @@ function parseDelegatedToolExecute(input) {
  * union, kept consistent here rather than reinvented: `completed` → `200 {result}`,
  * `denied`/`confirmation-denied` → `403 TOOL_OPERATION_DENIED`, `timed-out`/`cancelled` → a
  * SEC-005-redacted `500 INTERNAL_ERROR` (the real status/error goes to `onInternalError`, never the
- * wire).
+ * wire — unless the host supplies `deps.describeInternalError`, whose text then replaces the generic
+ * message on every redacted 500 below).
  *
  * `failed` splits in two, on `result.errorKind` (`@jini-ai/daemon`'s `ToolExecutor` sets it from
  * whether the handler threw `@jini-ai/core`'s `ToolInputError`): `'validation'` means the CALLER's
@@ -235,7 +264,7 @@ function toolExecutionResultToApiResult(deps, runId, toolId, result) {
             return err(createApiError('TOOL_OPERATION_DENIED', 'this operation was denied during confirmation'));
         case 'timed-out':
         case 'cancelled':
-            return err(reportInternalError(deps, 'delegated-tool-execute', result.status, runId, toolId));
+            return err(reportInternalError(deps, 'delegated-tool-execute', result.status, runId, toolId, result.status));
         case 'failed':
             if (result.errorKind === 'validation') {
                 return err(createApiError('BAD_REQUEST', result.error ?? 'invalid tool input'));
@@ -243,7 +272,7 @@ function toolExecutionResultToApiResult(deps, runId, toolId, result) {
             if (result.error && deps.isModelSafeToolFailure?.(result) === true) {
                 return err(createApiError('TOOL_EXECUTION_FAILED', result.error));
             }
-            return err(reportInternalError(deps, 'delegated-tool-execute', result.error ?? result.status, runId, toolId));
+            return err(reportInternalError(deps, 'delegated-tool-execute', result.error ?? result.status, runId, toolId, 'failed'));
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/http-kit",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Composable Express route packs and JSON-route transport for a @jini-ai/core daemon composition: request parsing, response serialization, same-origin guard, and a route-pack registrar.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,15 +40,15 @@
   "dependencies": {
     "express": "^4.21.0",
     "@jini-ai/core": "0.3.1",
+    "@jini-ai/protocol": "0.3.1",
     "@jini-ai/platform": "0.3.0",
-    "@jini-ai/agent-runtime": "0.3.9",
-    "@jini-ai/protocol": "0.3.0",
-    "@jini-ai/daemon": "0.3.7"
+    "@jini-ai/daemon": "0.3.8",
+    "@jini-ai/agent-runtime": "0.3.10"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@vitest/coverage-v8": "^2.1.9",
-    "@jini-ai/chat": "0.3.8"
+    "@jini-ai/chat": "0.3.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/dist/express/run-stream.d.ts

@@ -1,15 +0,0 @@
-/**
- * @module express/run-stream
- *
- * Express-specific mounting glue for the shared AG-UI SSE run-stream handler (`../run-stream.js`).
- * Express's `Request`/`Response` already *are* Node's raw `http.IncomingMessage`/
- * `http.ServerResponse` (Express's `Response` extends `http.ServerResponse` directly), so this
- * file's only job is resolving `req.params.runId` and handing the request/response straight
- * through — a few lines, not a reimplementation, per the design decision that motivated building
- * the SSE primitive once instead of duplicating it per transport.
- */
-import type { Express } from 'express';
-import { type RunStreamDeps } from '../run-stream.js';
-/** Mounts the AG-UI SSE run-stream route on `app`. A pack's `http(app, services)` calls this directly. */
-export declare function registerRunStreamRoute(app: Express, deps: RunStreamDeps): void;
-//# sourceMappingURL=run-stream.d.ts.map

package/dist/express/run-stream.js

@@ -1,11 +0,0 @@
-import { handleRunStreamRequest, RUN_STREAM_ROUTE_PATH } from '../run-stream.js';
-/** Mounts the AG-UI SSE run-stream route on `app`. A pack's `http(app, services)` calls this directly. */
-export function registerRunStreamRoute(app, deps) {
-    app.get(RUN_STREAM_ROUTE_PATH, async (req, res) => {
-        // `:runId` is a required path segment of RUN_STREAM_ROUTE_PATH — this handler is only ever
-        // reached via a URL that already matched it, so the param is always present at runtime even
-        // though @types/express types every param as possibly `undefined` in general.
-        await handleRunStreamRequest(req, res, req.params.runId, deps);
-    });
-}
-//# sourceMappingURL=run-stream.js.map

package/dist/express-index.d.ts

@@ -1,32 +0,0 @@
-/**
- * @module @jini/http/express
- *
- * The Express-native transport namespace: re-exports this package's existing flat Express
- * implementation (request parsing, response serialization, the mounting Adapter, the `/api`
- * security middleware, the route-registration guard, compat error helpers, the daemon-status
- * routes, and the runs/agents/host-tools route packs) under one namespace, mirroring
- * `./fastify/index.js`'s shape so a transport-switchable caller (`@jini/node-host`'s
- * `createLocalNodeDaemon`) can import either namespace symmetrically. Nothing here is a new
- * implementation — every export is the same flat file every other consumer of this package
- * already imports directly from the root barrel; this module exists only so `httpExpress.*` and
- * `httpFastify.*` read the same at call sites that need to pick a transport explicitly.
- */
-export type { AdapterContext } from './adapter.js';
-export { defineJsonRoute, mountJsonRoute } from './adapter.js';
-export type { ApiBearerAuthMiddlewareDeps, ApiOriginGuardMiddlewareDeps } from './api-security-middleware.js';
-export { registerApiBearerAuthMiddleware, registerApiOriginGuardMiddleware } from './api-security-middleware.js';
-export { createCompatApiError, createCompatApiErrorResponse, sendApiError as sendCompatApiError, } from './compat.js';
-export type { DaemonShutdownResponse, DaemonStatusDeps, DaemonStatusResponse, } from './daemon-status.js';
-export { daemonShutdownRoute, daemonStatusRoute, registerDaemonStatusRoutes } from './daemon-status.js';
-export { isLoopbackHostname, isLoopbackPeerAddress, localOriginFromHeader, normalizeLocalAuthority, requireLocalDaemonRequest, validateLocalDaemonRequest, } from './local-daemon-request.js';
-export type { OriginContext } from './origin.js';
-export { guardSameOrigin } from './origin.js';
-export { rawInput, validationError } from './request.js';
-export { registerRunStreamRoute } from './express/run-stream.js';
-export { sendApiError, sendJson, statusForError } from './response.js';
-export type { InstallRouteRegistrationGuardOptions, RouteRegistration } from './route-registration-guard.js';
-export { getRouteRegistrationInventory, guardedRouteKey, installRouteRegistrationGuard, } from './route-registration-guard.js';
-export { registerRunRoutes } from './runs.js';
-export { registerAgentRoutes } from './agents.js';
-export { registerHostToolsRoutes } from './host-tools.js';
-//# sourceMappingURL=express-index.d.ts.map

package/dist/express-index.js

@@ -1,14 +0,0 @@
-export { defineJsonRoute, mountJsonRoute } from './adapter.js';
-export { registerApiBearerAuthMiddleware, registerApiOriginGuardMiddleware } from './api-security-middleware.js';
-export { createCompatApiError, createCompatApiErrorResponse, sendApiError as sendCompatApiError, } from './compat.js';
-export { daemonShutdownRoute, daemonStatusRoute, registerDaemonStatusRoutes } from './daemon-status.js';
-export { isLoopbackHostname, isLoopbackPeerAddress, localOriginFromHeader, normalizeLocalAuthority, requireLocalDaemonRequest, validateLocalDaemonRequest, } from './local-daemon-request.js';
-export { guardSameOrigin } from './origin.js';
-export { rawInput, validationError } from './request.js';
-export { registerRunStreamRoute } from './express/run-stream.js';
-export { sendApiError, sendJson, statusForError } from './response.js';
-export { getRouteRegistrationInventory, guardedRouteKey, installRouteRegistrationGuard, } from './route-registration-guard.js';
-export { registerRunRoutes } from './runs.js';
-export { registerAgentRoutes } from './agents.js';
-export { registerHostToolsRoutes } from './host-tools.js';
-//# sourceMappingURL=express-index.js.map

package/dist/fastify/adapter.d.ts

@@ -1,31 +0,0 @@
-/**
- * The module's top orchestration layer: wires request parsing, the same-origin guard, a route's
- * `handle`, and response serialization into a single Fastify route handler. This is the only file
- * in this subtree that knows about Fastify's `request`/`reply` on the mounting side. Same job as
- * `../express/adapter.ts`'s `mountJsonRoute`, registered through Fastify's native
- * `fastify.route({ method, url, handler })` instead of Express's `app[method](path, handler)`.
- */
-import type { FastifyInstance } from 'fastify';
-import { type OriginContext } from './origin.js';
-import type { JsonRouteSpec } from '../types.js';
-/** Server startup state a mounted route needs to evaluate its same-origin guard. */
-export interface AdapterContext extends OriginContext {
-}
-/**
- * Identity function that pins a route spec's generic parameters at the definition site so
- * callers do not have to repeat them. The returned spec is consumed by `mountJsonRoute` (live)
- * and by tests (direct invocation of `route.parse` / `route.handle`).
- */
-export declare function defineJsonRoute<Input, Output, Deps>(spec: JsonRouteSpec<Input, Output, Deps>): JsonRouteSpec<Input, Output, Deps>;
-/**
- * Mounts one JsonRouteSpec on a Fastify instance. The Adapter is the only code here that knows
- * about request/reply; the route's parse and handle functions operate on `RouteInputContext` and
- * `Deps` respectively, so they are unit testable without Fastify.
- *
- * `exposeHeadRoute: false` is passed explicitly so a `GET` spec does not also register Fastify's
- * automatic `HEAD` sibling route — the Express version never registers one either, and a spec's
- * `handle` is not written to answer a bodyless `HEAD` request correctly (e.g. `daemonStatusRoute`
- * always returns a JSON body).
- */
-export declare function mountJsonRoute<Input, Output, Deps>(app: FastifyInstance, spec: JsonRouteSpec<Input, Output, Deps>, deps: Deps, adapter: AdapterContext): void;
-//# sourceMappingURL=adapter.d.ts.map

package/dist/fastify/adapter.js

@@ -1,64 +0,0 @@
-import { createApiError } from '@jini/protocol';
-import { rawInput } from './request.js';
-import { sendApiError, sendJson, statusForError } from './response.js';
-import { guardSameOrigin } from './origin.js';
-/**
- * Identity function that pins a route spec's generic parameters at the definition site so
- * callers do not have to repeat them. The returned spec is consumed by `mountJsonRoute` (live)
- * and by tests (direct invocation of `route.parse` / `route.handle`).
- */
-export function defineJsonRoute(spec) {
-    return spec;
-}
-/** Maps the shared, lower-case `HttpMethod` union to the upper-case method literal Fastify's `route()` expects. */
-const FASTIFY_METHOD = {
-    get: 'GET',
-    post: 'POST',
-    put: 'PUT',
-    delete: 'DELETE',
-    patch: 'PATCH',
-};
-/**
- * Mounts one JsonRouteSpec on a Fastify instance. The Adapter is the only code here that knows
- * about request/reply; the route's parse and handle functions operate on `RouteInputContext` and
- * `Deps` respectively, so they are unit testable without Fastify.
- *
- * `exposeHeadRoute: false` is passed explicitly so a `GET` spec does not also register Fastify's
- * automatic `HEAD` sibling route — the Express version never registers one either, and a spec's
- * `handle` is not written to answer a bodyless `HEAD` request correctly (e.g. `daemonStatusRoute`
- * always returns a JSON body).
- */
-export function mountJsonRoute(app, spec, deps, adapter) {
-    app.route({
-        method: FASTIFY_METHOD[spec.method],
-        url: spec.path,
-        exposeHeadRoute: false,
-        handler: async (req, reply) => {
-            try {
-                if (spec.requireSameOrigin) {
-                    const origin = guardSameOrigin(req, adapter);
-                    if (!origin.ok) {
-                        sendApiError(reply, statusForError(origin.error), origin.error);
-                        return;
-                    }
-                }
-                const parsed = spec.parse(rawInput(req));
-                if (!parsed.ok) {
-                    sendApiError(reply, statusForError(parsed.error), parsed.error);
-                    return;
-                }
-                const result = await spec.handle(parsed.value, deps);
-                if (!result.ok) {
-                    sendApiError(reply, statusForError(result.error), result.error);
-                    return;
-                }
-                sendJson(reply, spec.successStatus ?? 200, result.value);
-            }
-            catch (e) {
-                const message = e instanceof Error ? e.message : String(e);
-                sendApiError(reply, 500, createApiError('INTERNAL_ERROR', message));
-            }
-        },
-    });
-}
-//# sourceMappingURL=adapter.js.map

package/dist/fastify/agents.d.ts

@@ -1,13 +0,0 @@
-/**
- * @module fastify/agents
- *
- * Fastify-mounting glue for `../agents.js`'s `agentListRoute` — the exact same `JsonRouteSpec`
- * the Express mounting in `../agents.js` uses, just mounted through this subtree's own
- * `mountJsonRoute` instead.
- */
-import type { FastifyInstance } from 'fastify';
-import { type AgentsHttpDeps } from '../agents.js';
-import { type AdapterContext } from './adapter.js';
-/** Mounts `GET /api/agents` on `app` — the Fastify-native equivalent of `../agents.js`'s `registerAgentRoutes`. */
-export declare function registerAgentRoutes(app: FastifyInstance, deps: AgentsHttpDeps, adapter: AdapterContext): void;
-//# sourceMappingURL=agents.d.ts.map

package/dist/fastify/agents.js

@@ -1,7 +0,0 @@
-import { agentListRoute } from '../agents.js';
-import { mountJsonRoute } from './adapter.js';
-/** Mounts `GET /api/agents` on `app` — the Fastify-native equivalent of `../agents.js`'s `registerAgentRoutes`. */
-export function registerAgentRoutes(app, deps, adapter) {
-    mountJsonRoute(app, agentListRoute, deps, adapter);
-}
-//# sourceMappingURL=agents.js.map

package/dist/fastify/api-security-middleware.d.ts

@@ -1,64 +0,0 @@
-/**
- * @module fastify/api-security-middleware
- *
- * The two `/api` request gates a locally-bound daemon needs before any route handler runs:
- * bearer-token authentication (optional, active only when a token is configured) and cross-origin
- * rejection (always active). Same job and decision logic as `../express/api-security-middleware.ts`
- * (see that file's own doc for the full drop-list this was genericized from), reimplemented on
- * Fastify's native `onRequest` lifecycle hook (`app.addHook('onRequest', ...)`) in place of
- * Express's `app.use('/api', ...)` path-scoped middleware. Fastify has no first-class "scope this
- * hook to a URL prefix" primitive at the plain-instance level (that requires nesting the routes
- * themselves inside a `.register()` plugin with a `prefix`, which `mountPackHttp`'s pack-agnostic
- * mounting does not do), so both hooks below scope themselves manually by checking the request's
- * own path against the `/api` prefix before applying either gate — the observable behavior is
- * identical to the Express version's `app.use('/api', ...)` scoping.
- */
-import type { FastifyInstance } from 'fastify';
-import { type ApiTokenAuthEnvConfig } from '@jini/core';
-export interface ApiBearerAuthMiddlewareDeps {
-    /** Env var names for the token/disable flags. Defaults to `JINI_API_TOKEN` / `JINI_DISABLE_API_AUTH`. */
-    tokenConfig?: ApiTokenAuthEnvConfig;
-    /** Defaults to `process.env`. Threaded through so tests never have to mutate real process env. */
-    env?: NodeJS.ProcessEnv;
-}
-/**
- * Registers a bearer-token gate on every `/api/*` route, active only when
- * {@link isApiTokenMiddlewareEnabled} says a token is configured and auth hasn't been disabled.
- * When active: open-probe paths and loopback peers skip the check unconditionally; every other
- * request must send `Authorization: Bearer <token>` matching the configured token exactly, or the
- * request is rejected with 401 before reaching any route handler.
- *
- * @param app - The Fastify instance to register the gate on.
- * @param deps - See {@link ApiBearerAuthMiddlewareDeps}. Both fields are optional; omitting `deps`
- * entirely reads `JINI_API_TOKEN`/`JINI_DISABLE_API_AUTH` from real `process.env`.
- * @returns Nothing. Registers zero hooks (a deliberate no-op, not a bug) when no token is configured.
- * @complexity Setup is O(1). Each gated request is O(1) (one Set lookup, one regex match).
- * @overallScore 100/100
- */
-export declare function registerApiBearerAuthMiddleware(app: FastifyInstance, deps?: ApiBearerAuthMiddlewareDeps): void;
-export interface ApiOriginGuardMiddlewareDeps {
-    /** The host this daemon is bound to — compared against a request's `Host`/`Origin` headers. */
-    host: string;
-    /** Extra allow-listed origins (e.g. a reverse-proxy's public origin). Defaults to none. */
-    extraAllowedOrigins?: readonly string[];
-    /** Returns the daemon's resolved listen port, or a falsy value before it has resolved. */
-    getResolvedPort: () => number | null | undefined;
-    /** Defaults to `process.env`. Threaded through so `JINI_WEB_PORT` is testable without mutating real process env. */
-    env?: NodeJS.ProcessEnv;
-}
-/**
- * Registers an unconditional cross-origin gate on every `/api/*` route: non-browser clients (no
- * `Origin` header) and requests whose `Origin` resolves to a loopback, private-LAN, or explicitly
- * allow-listed origin are let through; everything else is rejected with 403. `Origin: null`
- * (typically a sandboxed iframe) is always rejected — see the Express version's doc for why the
- * origin daemon's safe-GET exemption for that case was dropped.
- *
- * @param app - The Fastify instance to register the gate on.
- * @param deps - See {@link ApiOriginGuardMiddlewareDeps}.
- * @returns Nothing. Unlike the bearer-token gate, this always registers its hook — there is
- * no "disabled" state.
- * @complexity Setup is O(1). Each gated request is O(p) in the number of allowed ports (typically 1-2).
- * @overallScore 100/100
- */
-export declare function registerApiOriginGuardMiddleware(app: FastifyInstance, deps: ApiOriginGuardMiddlewareDeps): void;
-//# sourceMappingURL=api-security-middleware.d.ts.map

package/dist/fastify/api-security-middleware.js

@@ -1,139 +0,0 @@
-import { apiTokenFromEnv, isApiTokenMiddlewareEnabled, } from '@jini/core';
-import { isLoopbackPeerAddress } from './local-daemon-request.js';
-import { allowedBrowserPorts, isAllowedBrowserOrigin } from '../origin-validation.js';
-/** Health/readiness/version probes stay reachable without a bearer token so monitoring never needs one. Both the mount-relative and `/api`-prefixed forms are kept for parity with the Express version's set (only the `/api`-prefixed forms are ever reachable here, since both hooks below already require the path to start with `/api` before this set is even consulted). */
-const OPEN_PROBE_PATHS = new Set([
-    '/health',
-    '/api/health',
-    '/ready',
-    '/api/ready',
-    '/version',
-    '/api/version',
-]);
-const BEARER_TOKEN_PATTERN = /^Bearer\s+(\S+)\s*$/i;
-const DEFAULT_TOKEN_CONFIG = {
-    tokenEnvVar: 'JINI_API_TOKEN',
-    disableEnvVar: 'JINI_DISABLE_API_AUTH',
-};
-/**
- * The request path with no query string — Fastify's `request.url` (unlike Express's
- * `request.path`) always includes the query string, so this strips it to match Express's
- * comparison semantics. `req.url` is typed as a required `string` on `FastifyRequest`
- * (never `undefined`), and `String.prototype.split` on a string separator always returns an
- * array with at least one element, so the `[0]` index is provably defined — the non-null
- * assertion documents that guarantee instead of masking it behind an unreachable `?? ''` fallback
- * that could never be exercised by a real request.
- */
-function requestPath(req) {
-    return req.url.split('?')[0];
-}
-/**
- * Registers a bearer-token gate on every `/api/*` route, active only when
- * {@link isApiTokenMiddlewareEnabled} says a token is configured and auth hasn't been disabled.
- * When active: open-probe paths and loopback peers skip the check unconditionally; every other
- * request must send `Authorization: Bearer <token>` matching the configured token exactly, or the
- * request is rejected with 401 before reaching any route handler.
- *
- * @param app - The Fastify instance to register the gate on.
- * @param deps - See {@link ApiBearerAuthMiddlewareDeps}. Both fields are optional; omitting `deps`
- * entirely reads `JINI_API_TOKEN`/`JINI_DISABLE_API_AUTH` from real `process.env`.
- * @returns Nothing. Registers zero hooks (a deliberate no-op, not a bug) when no token is configured.
- * @complexity Setup is O(1). Each gated request is O(1) (one Set lookup, one regex match).
- * @overallScore 100/100
- */
-export function registerApiBearerAuthMiddleware(app, deps = {}) {
-    const tokenConfig = deps.tokenConfig ?? DEFAULT_TOKEN_CONFIG;
-    const env = deps.env ?? process.env;
-    if (!isApiTokenMiddlewareEnabled(tokenConfig, env))
-        return;
-    const apiToken = apiTokenFromEnv(tokenConfig, env);
-    app.addHook('onRequest', (req, reply, done) => {
-        const path = requestPath(req);
-        if (!path.startsWith('/api')) {
-            done();
-            return;
-        }
-        if (OPEN_PROBE_PATHS.has(path)) {
-            done();
-            return;
-        }
-        // Loopback short-circuit: the desktop UI / local CLI never carry a bearer, and a reverse
-        // proxy in front of a non-loopback bind must always forward the real bearer itself — so this
-        // is intentionally not fooled by a proxied `X-Forwarded-For` header.
-        if (isLoopbackPeerAddress(req.socket?.remoteAddress)) {
-            done();
-            return;
-        }
-        const match = BEARER_TOKEN_PATTERN.exec(req.headers.authorization ?? '');
-        if (!match || match[1] !== apiToken) {
-            reply.code(401).send({
-                error: {
-                    code: 'API_TOKEN_REQUIRED',
-                    message: `Authorization: Bearer <${tokenConfig.tokenEnvVar}> required`,
-                },
-            });
-            return;
-        }
-        done();
-    });
-}
-/**
- * Chrome may strip the port from the `Origin` header on same-origin GET requests. Used only as a
- * narrow fallback for safe, idempotent GET requests once the exact-match check below has already
- * failed — mutating routes always require an exact origin/host match.
- */
-function isPortlessLoopbackOrigin(origin) {
-    return /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])$/.test(origin);
-}
-/**
- * Registers an unconditional cross-origin gate on every `/api/*` route: non-browser clients (no
- * `Origin` header) and requests whose `Origin` resolves to a loopback, private-LAN, or explicitly
- * allow-listed origin are let through; everything else is rejected with 403. `Origin: null`
- * (typically a sandboxed iframe) is always rejected — see the Express version's doc for why the
- * origin daemon's safe-GET exemption for that case was dropped.
- *
- * @param app - The Fastify instance to register the gate on.
- * @param deps - See {@link ApiOriginGuardMiddlewareDeps}.
- * @returns Nothing. Unlike the bearer-token gate, this always registers its hook — there is
- * no "disabled" state.
- * @complexity Setup is O(1). Each gated request is O(p) in the number of allowed ports (typically 1-2).
- * @overallScore 100/100
- */
-export function registerApiOriginGuardMiddleware(app, deps) {
-    const { host, getResolvedPort } = deps;
-    const extraAllowedOrigins = deps.extraAllowedOrigins ?? [];
-    const env = deps.env ?? process.env;
-    app.addHook('onRequest', (req, reply, done) => {
-        const path = requestPath(req);
-        if (!path.startsWith('/api')) {
-            done();
-            return;
-        }
-        const origin = req.headers.origin;
-        if (origin == null || origin === '') {
-            done();
-            return;
-        }
-        if (origin === 'null') {
-            reply.code(403).send({ error: 'Origin: null not allowed for this route' });
-            return;
-        }
-        // Fail-closed: block every browser origin until the daemon's real listen port is known, so a
-        // request arriving in the brief window before `.listen()` resolves can never be compared
-        // against a wrong or default port.
-        const resolvedPort = getResolvedPort();
-        if (!resolvedPort) {
-            reply.code(403).send({ error: 'Server initializing' });
-            return;
-        }
-        const ports = allowedBrowserPorts(resolvedPort, env);
-        if (!isAllowedBrowserOrigin(origin, req.headers.host, ports, host, [...extraAllowedOrigins])) {
-            if (req.method !== 'GET' || !isPortlessLoopbackOrigin(String(origin))) {
-                reply.code(403).send({ error: 'Cross-origin requests are not allowed' });
-                return;
-            }
-        }
-        done();
-    });
-}
-//# sourceMappingURL=api-security-middleware.js.map

package/dist/fastify/compat.d.ts

@@ -1,22 +0,0 @@
-/**
- * Legacy-shaped error helpers: build/send an `ApiError` from separate `code`/`message`/`init`
- * arguments, matching call sites that predate `JsonRouteSpec`/`mountJsonRoute` (e.g. a host
- * application's own hand-mounted routes). No internal dependencies. `sendApiError` here is
- * deliberately the same name as `response.ts`'s `ApiError`-object-taking `sendApiError` — they
- * are different signatures for the same "send an error" job at two call-site generations; the
- * package's `fastify/index.ts` barrel re-exports this one as `sendCompatApiError` to keep both
- * addressable without a collision. Deliberately duplicated from `../express/compat.ts` — see
- * `./response.ts`'s top-of-module doc for why this subtree does not import from `express/`.
- */
-import type { ApiError, ApiErrorCode, ApiErrorResponse } from '@jini/protocol';
-import type { FastifyReply } from 'fastify';
-/** Builds an `ApiError` from separate `code`/`message`/`init` arguments (legacy call shape). */
-export declare function createCompatApiError(code: ApiErrorCode, message: string, init?: Omit<ApiError, 'code' | 'message'>): ApiError;
-/** Wraps `createCompatApiError`'s result in the standard `{ error }` envelope. */
-export declare function createCompatApiErrorResponse(code: ApiErrorCode, message: string, init?: Omit<ApiError, 'code' | 'message'>): ApiErrorResponse;
-/**
- * Writes an `ApiError` response built from separate `code`/`message`/`init` arguments (legacy
- * call shape) with the given status code. Exported from `fastify/index.ts` as `sendCompatApiError`.
- */
-export declare function sendApiError(reply: FastifyReply, status: number, code: ApiErrorCode, message: string, init?: Omit<ApiError, 'code' | 'message'>): FastifyReply;
-//# sourceMappingURL=compat.d.ts.map

package/dist/fastify/compat.js

@@ -1,16 +0,0 @@
-/** Builds an `ApiError` from separate `code`/`message`/`init` arguments (legacy call shape). */
-export function createCompatApiError(code, message, init = {}) {
-    return { code, message, ...init };
-}
-/** Wraps `createCompatApiError`'s result in the standard `{ error }` envelope. */
-export function createCompatApiErrorResponse(code, message, init = {}) {
-    return { error: createCompatApiError(code, message, init) };
-}
-/**
- * Writes an `ApiError` response built from separate `code`/`message`/`init` arguments (legacy
- * call shape) with the given status code. Exported from `fastify/index.ts` as `sendCompatApiError`.
- */
-export function sendApiError(reply, status, code, message, init = {}) {
-    return reply.code(status).send(createCompatApiErrorResponse(code, message, init));
-}
-//# sourceMappingURL=compat.js.map

package/dist/fastify/daemon-status.d.ts

@@ -1,22 +0,0 @@
-/**
- * @module fastify/daemon-status
- *
- * Mounts the generic daemon status + shutdown routes through the Fastify Adapter. The route
- * SPECS themselves (`daemonStatusRoute`/`daemonShutdownRoute` — pure `defineJsonRoute`-shaped
- * data plus framework-agnostic `parse`/`handle` functions, see `../daemon-status.ts`'s own doc
- * for their full provenance) are intentionally NOT duplicated here: they never reference Express
- * at runtime (`../daemon-status.ts` only imports `type { Express }` for its own
- * `registerDaemonStatusRoutes`'s parameter — a type-only import that TypeScript's
- * `verbatimModuleSyntax` erases from the compiled output entirely, so importing the specs from
- * that module does not pull the `express` package into this subtree at runtime). This file's own
- * job is only the Fastify-specific mounting wrapper, calling `./adapter.js`'s Fastify
- * `mountJsonRoute` instead of the Express one.
- */
-import type { FastifyInstance } from 'fastify';
-import { daemonShutdownRoute, daemonStatusRoute, type DaemonShutdownResponse, type DaemonStatusDeps, type DaemonStatusResponse } from '../daemon-status.js';
-import { type AdapterContext } from './adapter.js';
-export { daemonShutdownRoute, daemonStatusRoute };
-export type { DaemonShutdownResponse, DaemonStatusDeps, DaemonStatusResponse };
-/** Mounts both daemon-status routes on `app`. A pack's `http(app, services)` calls this directly. */
-export declare function registerDaemonStatusRoutes(app: FastifyInstance, deps: DaemonStatusDeps, adapter: AdapterContext): void;
-//# sourceMappingURL=daemon-status.d.ts.map

package/dist/fastify/daemon-status.js

@@ -1,9 +0,0 @@
-import { daemonShutdownRoute, daemonStatusRoute, } from '../daemon-status.js';
-import { mountJsonRoute } from './adapter.js';
-export { daemonShutdownRoute, daemonStatusRoute };
-/** Mounts both daemon-status routes on `app`. A pack's `http(app, services)` calls this directly. */
-export function registerDaemonStatusRoutes(app, deps, adapter) {
-    mountJsonRoute(app, daemonStatusRoute, deps, adapter);
-    mountJsonRoute(app, daemonShutdownRoute, deps, adapter);
-}
-//# sourceMappingURL=daemon-status.js.map

package/dist/fastify/host-tools.d.ts

@@ -1,13 +0,0 @@
-/**
- * @module fastify/host-tools
- *
- * Fastify-mounting glue for `../host-tools.js`'s `hostEditorsRoute`/`openResourceInEditorRoute` —
- * the exact same `JsonRouteSpec` objects the Express mounting in `../host-tools.js` uses, just
- * mounted through this subtree's own `mountJsonRoute` instead.
- */
-import type { FastifyInstance } from 'fastify';
-import { type HostToolsOpenInDeps } from '../host-tools.js';
-import { type AdapterContext } from './adapter.js';
-/** Mounts `GET /api/editors` and `POST /api/resources/:resourceRef/open-in` on `app` — the Fastify-native equivalent of `../host-tools.js`'s `registerHostToolsRoutes`. */
-export declare function registerHostToolsRoutes(app: FastifyInstance, adapter: AdapterContext, openInDeps?: HostToolsOpenInDeps): void;
-//# sourceMappingURL=host-tools.d.ts.map

package/dist/fastify/host-tools.js

@@ -1,8 +0,0 @@
-import { hostEditorsRoute, openResourceInEditorRoute } from '../host-tools.js';
-import { mountJsonRoute } from './adapter.js';
-/** Mounts `GET /api/editors` and `POST /api/resources/:resourceRef/open-in` on `app` — the Fastify-native equivalent of `../host-tools.js`'s `registerHostToolsRoutes`. */
-export function registerHostToolsRoutes(app, adapter, openInDeps = {}) {
-    mountJsonRoute(app, hostEditorsRoute, {}, adapter);
-    mountJsonRoute(app, openResourceInEditorRoute, openInDeps, adapter);
-}
-//# sourceMappingURL=host-tools.js.map