@jini-ai/http-kit 0.2.1

package/dist/agents.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module agents
+ *
+ * `GET /api/agents` — lists the agents a host can expose to a client,
+ * including host-probed availability/model metadata when supplied.
+ * `POST /api/agents/rescan` asks the host to invalidate its discovery cache
+ * and probe again.
+ *
+ * `listAgents` is injected (matching `daemon-status.ts`/`active-context.ts`'s
+ * DI convention) rather than this module importing `@jini-ai/agent-runtime`
+ * directly — a host typically already has that package's `AGENT_DEFS` array
+ * in scope and just needs to project it, and this keeps `@jini-ai/http-kit` from
+ * taking on a dependency on subprocess discovery. The host owns probing,
+ * timeouts, caching, PATH/env policy, and the projection of spawn-only
+ * metadata; this transport only serializes the safe summary.
+ */
+import type { Express } from 'express';
+import { type AdapterContext } from './adapter.js';
+export interface AgentModelSummary {
+    readonly id: string;
+    readonly label: string;
+}
+/**
+ * Client-safe agent discovery data. Optional probe fields preserve the
+ * original static-registry contract for hosts that only expose `{id, name}`.
+ * Spawn internals (`bin`, resolved path, argv builders, env) never cross HTTP.
+ */
+export interface AgentSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly available?: boolean;
+    readonly version?: string | null;
+    readonly authStatus?: 'ok' | 'missing' | 'unknown';
+    readonly models?: readonly AgentModelSummary[];
+    readonly reasoningOptions?: readonly AgentModelSummary[];
+    readonly modelsSource?: 'live' | 'fallback';
+    readonly supportsCustomModel?: boolean;
+    readonly diagnostic?: string;
+}
+export interface AgentsHttpDeps {
+    /** Returns the host's cached or freshly resolved client-safe agent inventory. */
+    readonly listAgents: () => Promise<readonly AgentSummary[]> | readonly AgentSummary[];
+    /** Forces host-owned discovery to run again. Falls back to `listAgents` when omitted. */
+    readonly rescanAgents?: () => Promise<readonly AgentSummary[]> | readonly AgentSummary[];
+}
+export interface AgentListResponse {
+    readonly agents: readonly AgentSummary[];
+}
+/** `GET /api/agents` — read-only, no side effects; matches `runListRoute`/`runStatusRoute`'s posture of not requiring same-origin. */
+export declare const agentListRoute: import("./types.js").JsonRouteSpec<void, AgentListResponse, AgentsHttpDeps>;
+/** `POST /api/agents/rescan` — explicit state refresh, protected by the local same-origin gate. */
+export declare const agentRescanRoute: import("./types.js").JsonRouteSpec<void, AgentListResponse, AgentsHttpDeps>;
+/** Mounts the read and explicit-rescan agent discovery routes. */
+export declare function registerAgentRoutes(app: Express, deps: AgentsHttpDeps, adapter: AdapterContext): void;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAGpF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,GAAG,SAAS,YAAY,EAAE,CAAC;IACtF,yFAAyF;IACzF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,GAAG,SAAS,YAAY,EAAE,CAAC;CAC1F;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,sIAAsI;AACtI,eAAO,MAAM,cAAc,6EAKzB,CAAC;AAEH,mGAAmG;AACnG,eAAO,MAAM,gBAAgB,6EAM3B,CAAC;AAEH,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAGrG"}

package/dist/agents.js

@@ -0,0 +1,23 @@
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { ok } from './types.js';
+/** `GET /api/agents` — read-only, no side effects; matches `runListRoute`/`runStatusRoute`'s posture of not requiring same-origin. */
+export const agentListRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/agents',
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => ok({ agents: await deps.listAgents() }),
+});
+/** `POST /api/agents/rescan` — explicit state refresh, protected by the local same-origin gate. */
+export const agentRescanRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/agents/rescan',
+    requireSameOrigin: true,
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => ok({ agents: await (deps.rescanAgents ?? deps.listAgents)() }),
+});
+/** Mounts the read and explicit-rescan agent discovery routes. */
+export function registerAgentRoutes(app, deps, adapter) {
+    mountJsonRoute(app, agentListRoute, deps, adapter);
+    mountJsonRoute(app, agentRescanRoute, deps, adapter);
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAuB,MAAM,cAAc,CAAC;AACpF,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAoChC,sIAAsI;AACtI,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAA0C;IACrF,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;CACxE,CAAC,CAAC;AAEH,mGAAmG;AACnG,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAA0C;IACvF,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,oBAAoB;IAC1B,iBAAiB,EAAE,IAAI;IACvB,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;CAC/F,CAAC,CAAC;AAEH,kEAAkE;AAClE,MAAM,UAAU,mBAAmB,CAAC,GAAY,EAAE,IAAoB,EAAE,OAAuB;IAC7F,cAAc,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACnD,cAAc,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC"}

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

@@ -0,0 +1,146 @@
+import type { Express, NextFunction, Request, Response } from 'express';
+import { type ApiTokenAuthEnvConfig } from '@jini-ai/core';
+/**
+ * Extracts the token from an `Authorization: Bearer <token>` header value. The scheme is
+ * case-insensitive per RFC 7235 §2.1; the token itself is not.
+ *
+ * Shared by every bearer gate in this package so the accepted header grammar is defined exactly
+ * once — three separate copies of this regex is three chances for them to disagree about what
+ * counts as a well-formed header.
+ *
+ * @param header - The raw `Authorization` header value, or `undefined` when absent.
+ * @returns The token, or `null` when the header is absent or not a well-formed bearer header.
+ * @complexity O(n) in the header length.
+ * @overallScore 100/100
+ */
+export declare function bearerTokenFromHeader(header: string | undefined): string | null;
+/**
+ * Constant-time token comparison. Length is compared first and NOT in constant time — that leaks
+ * only the expected token's length, which for a generated secret is fixed and not itself a secret,
+ * never any of its bytes. `timingSafeEqual` throws on a length mismatch, so the early return is
+ * required rather than merely an optimization.
+ *
+ * Every bearer gate in this package routes through here instead of `===`. A plain string compare
+ * short-circuits on the first differing byte, which makes the comparison's duration a function of
+ * how many leading bytes the presented token got right — enough, over many requests, to recover a
+ * token one byte at a time.
+ *
+ * @param presented - The token from the request's `Authorization` header.
+ * @param expected - The configured token to match against.
+ * @returns `true` only on an exact match.
+ * @complexity O(n) in the token length, with no data-dependent early exit.
+ * @overallScore 100/100
+ */
+export declare function timingSafeTokenMatch(presented: string, expected: string): boolean;
+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;
+    /**
+     * Whether an unproxied loopback peer may skip the bearer check. Defaults to `true` — the
+     * affordance a desktop UI or local CLI talking to its own daemon relies on.
+     *
+     * Set to `false` for any deployment where a process other than a trusted local client can open a
+     * loopback connection to this daemon, which includes every same-host reverse-proxy deployment
+     * (see the forwarded-header note at the check itself) and any multi-tenant or shared host. There
+     * is no way to tell those peers apart by socket address alone, so this is the host's call to
+     * make, not one this middleware can infer. {@link requireStrictBearerToken} is the same posture
+     * for a daemon that should never have had the exemption in the first place.
+     */
+    trustLoopbackPeers?: boolean;
+}
+/**
+ * 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 Express app 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 middleware (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: Express, deps?: ApiBearerAuthMiddlewareDeps): void;
+export interface StrictBearerTokenDeps {
+    /**
+     * Env var carrying the expected token. Required with no default: a gate this strict must name the
+     * secret it enforces, and this package has no business guessing a host's env-var name.
+     */
+    readonly tokenEnvVar: string;
+    /** Defaults to `process.env`. Threaded through so tests never have to mutate real process env. */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * Exact request paths this gate does not apply to. Defaults to none — this is a gate-everything
+     * primitive, and each exemption must be opted into explicitly at the mount site with a stated
+     * reason. Matched by exact equality, never by prefix, so a longer path that merely starts with an
+     * exempt one stays gated.
+     */
+    readonly exemptPaths?: readonly string[];
+}
+/**
+ * Builds a bearer gate with **no loopback exemption and no disable flag** — for a daemon whose
+ * threat model is "another process running as the same OS user", not "a remote attacker".
+ *
+ * This is deliberately not {@link registerApiBearerAuthMiddleware}. That gate short-circuits for any
+ * loopback peer before it ever reads the `Authorization` header, which is the right affordance for a
+ * desktop UI or local CLI talking to its own daemon, and a no-op against the threat here: a
+ * `127.0.0.1` bind keeps remote hosts out but does nothing about a co-resident process, and a
+ * sidecar daemon that can start real agent runs and execute real tools is exactly the kind of thing
+ * such a process would want to reach. This gate treats a request from `127.0.0.1` like any other.
+ *
+ * The posture matches `remote-run-events.ts`'s own token gate, which made the same call for the same
+ * reason on a single route; this generalizes it to a whole `/api` surface.
+ *
+ * Fail-closed contract:
+ * - token env var unset/empty -> **503**, never a silent pass-through. A misconfigured daemon
+ *   refuses to serve rather than serving unauthenticated callers.
+ * - missing / malformed / wrong token -> **401**.
+ * - exact match -> `next()`.
+ *
+ * The env var is read on every request rather than captured at factory time: a host that mints a
+ * per-boot token may not have done so yet when its module graph is first evaluated, and re-reading
+ * costs one property lookup.
+ *
+ * @param deps - See {@link StrictBearerTokenDeps}. `tokenEnvVar` is required.
+ * @returns Express middleware. Mount it **unprefixed** — `app.use(handler)` — before any route
+ * registrar and before the JSON body parser, so an unauthenticated caller's body is never parsed.
+ * @complexity O(1) per request plus O(n) in the token length for the constant-time comparison.
+ * @overallScore 95/100 — Medium: mounting under a prefix (`app.use('/api', handler)`) silently breaks
+ * `exemptPaths`. Express strips the mount prefix from `req.path`, so an entry written as a full path
+ * (`/api/delegated-tool-calls`) stops matching and the gate rejects a caller the mount site meant to
+ * exempt. Nothing type-checks that, and the failure is a 401 on a route that is supposed to be open
+ * rather than the reverse — noisy rather than dangerous, but confusing to diagnose. Documented rather
+ * than defended against in code: normalizing `req.baseUrl + req.path` here would silently accept both
+ * mount styles and remove the caller's ability to reason about which paths its entries refer to.
+ */
+export declare function requireStrictBearerToken(deps: StrictBearerTokenDeps): (req: Request, res: Response, next: NextFunction) => 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 this module's doc for why the origin
+ * daemon's safe-GET exemption for that case was dropped.
+ *
+ * @param app - The Express app to register the gate on.
+ * @param deps - See {@link ApiOriginGuardMiddlewareDeps}.
+ * @returns Nothing. Unlike the bearer-token gate, this always registers its middleware — 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: Express, deps: ApiOriginGuardMiddlewareDeps): void;
+//# sourceMappingURL=api-security-middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-security-middleware.d.ts","sourceRoot":"","sources":["../src/api-security-middleware.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAC;AAgBvB;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKjF;AAED,MAAM,WAAW,2BAA2B;IAC1C,yGAAyG;IACzG,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,2BAAgC,GAAG,IAAI,CA6C1G;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,qBAAqB,IAKf,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CA2B1G;AAED,MAAM,WAAW,4BAA4B;IAC3C,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,0FAA0F;IAC1F,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjD,oHAAoH;IACpH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,4BAA4B,GAAG,IAAI,CAmCvG"}

package/dist/api-security-middleware.js

@@ -0,0 +1,276 @@
+/**
+ * @module api-security-middleware
+ *
+ * The `/api` request gates a locally-bound daemon needs before any route handler runs:
+ * bearer-token authentication (optional, active only when a token is configured), cross-origin
+ * rejection (always active), and — for a daemon whose threat model is a co-resident process rather
+ * than a remote one — a strict bearer gate with no loopback exemption and no disable flag
+ * ({@link requireStrictBearerToken}). The first two were genericized from an origin daemon's inline
+ * `startServer` middleware pair — see `source-map.md` for the exact drop-list. All are plain Express
+ * middleware factories with configuration injected, so none reads a hardcoded env var name or an
+ * OD-specific request shape.
+ *
+ * The two token gates differ in exactly one load-bearing way and are not interchangeable: the
+ * optional one lets any loopback peer through unauthenticated, the strict one does not. Picking the
+ * wrong one is a silent no-op rather than a visible error, so see each function's own doc before
+ * choosing.
+ *
+ * **Dropped, not carried over** (see `source-map.md`'s transformation table for the full
+ * reasoning): the project-preview-scope GET exemption, the zero-config browser-extension
+ * ("clipper") bypass, the live-artifacts-preview bypass, and the `Origin: null` safe-GET
+ * allow-list regex — all four name or exist solely for OD product routes with no meaning in the
+ * generic engine. `Origin: null` is therefore always rejected here, not conditionally allowed.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { apiTokenFromEnv, isApiTokenMiddlewareEnabled, } from '@jini-ai/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 listed because this middleware is always registered via `app.use('/api', ...)`, under which Express strips the `/api` prefix from `req.path` for a request to `/api/health` — the prefixed form is kept for parity with the origin module's own set rather than dropped as dead, in case a future caller mounts this middleware unprefixed. */
+const OPEN_PROBE_PATHS = new Set([
+    '/health',
+    '/api/health',
+    '/ready',
+    '/api/ready',
+    '/version',
+    '/api/version',
+]);
+const BEARER_TOKEN_PATTERN = /^Bearer\s+(\S+)\s*$/i;
+/**
+ * Extracts the token from an `Authorization: Bearer <token>` header value. The scheme is
+ * case-insensitive per RFC 7235 §2.1; the token itself is not.
+ *
+ * Shared by every bearer gate in this package so the accepted header grammar is defined exactly
+ * once — three separate copies of this regex is three chances for them to disagree about what
+ * counts as a well-formed header.
+ *
+ * @param header - The raw `Authorization` header value, or `undefined` when absent.
+ * @returns The token, or `null` when the header is absent or not a well-formed bearer header.
+ * @complexity O(n) in the header length.
+ * @overallScore 100/100
+ */
+export function bearerTokenFromHeader(header) {
+    return BEARER_TOKEN_PATTERN.exec(header ?? '')?.[1] ?? null;
+}
+/**
+ * Constant-time token comparison. Length is compared first and NOT in constant time — that leaks
+ * only the expected token's length, which for a generated secret is fixed and not itself a secret,
+ * never any of its bytes. `timingSafeEqual` throws on a length mismatch, so the early return is
+ * required rather than merely an optimization.
+ *
+ * Every bearer gate in this package routes through here instead of `===`. A plain string compare
+ * short-circuits on the first differing byte, which makes the comparison's duration a function of
+ * how many leading bytes the presented token got right — enough, over many requests, to recover a
+ * token one byte at a time.
+ *
+ * @param presented - The token from the request's `Authorization` header.
+ * @param expected - The configured token to match against.
+ * @returns `true` only on an exact match.
+ * @complexity O(n) in the token length, with no data-dependent early exit.
+ * @overallScore 100/100
+ */
+export function timingSafeTokenMatch(presented, expected) {
+    const presentedBytes = Buffer.from(presented, 'utf8');
+    const expectedBytes = Buffer.from(expected, 'utf8');
+    if (presentedBytes.length !== expectedBytes.length)
+        return false;
+    return timingSafeEqual(presentedBytes, expectedBytes);
+}
+/**
+ * Headers a reverse proxy adds when it forwards a request on behalf of some other client. Their
+ * *values* are deliberately never read — this package does not trust them to identify anyone (that
+ * is the `X-Forwarded-For` spoofing trap the loopback check was written to avoid). Only their
+ * presence is used, and only to withhold a privilege: a request carrying one was relayed by a
+ * proxy, so it is not the local desktop/CLI peer the loopback exemption exists for.
+ */
+const PROXY_FORWARDING_HEADERS = ['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'forwarded'];
+function looksProxied(req) {
+    return PROXY_FORWARDING_HEADERS.some((header) => {
+        const value = req.headers[header];
+        return typeof value === 'string' ? value.length > 0 : Array.isArray(value) && value.length > 0;
+    });
+}
+const DEFAULT_TOKEN_CONFIG = {
+    tokenEnvVar: 'JINI_API_TOKEN',
+    disableEnvVar: 'JINI_DISABLE_API_AUTH',
+};
+/**
+ * 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 Express app 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 middleware (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);
+    const trustLoopbackPeers = deps.trustLoopbackPeers ?? true;
+    app.use('/api', (req, res, next) => {
+        if (OPEN_PROBE_PATHS.has(req.path)) {
+            next();
+            return;
+        }
+        // Loopback short-circuit: the desktop UI / local CLI never carry a bearer, and the peer address
+        // is read from the socket rather than `X-Forwarded-For` so a spoofed forwarding header can
+        // never *grant* the exemption.
+        //
+        // That alone is not enough. A reverse proxy running on the same host as the daemon — nginx or
+        // caddy on the same box, proxying to a bind on 127.0.0.1, an extremely common deployment —
+        // terminates the client's connection itself and opens its own from loopback, so every
+        // externally-originated request through it arrives with a loopback socket address. Trusting the
+        // socket address alone would hand the exemption to the entire public internet.
+        //
+        // So the exemption is withheld from any request carrying a forwarding header: those are added
+        // by the proxy, not by the local desktop/CLI clients this exemption exists for. The header's
+        // value is still never read — presence only ever *removes* the exemption, so a caller who
+        // forges one gains nothing and simply has to present the bearer like anyone else. A proxy
+        // deployment that strips its own forwarding headers is not covered by this and must set
+        // `trustLoopbackPeers: false`, which is also the correct setting for any host where an
+        // untrusted co-resident process can reach the port.
+        if (trustLoopbackPeers && isLoopbackPeerAddress(req.socket?.remoteAddress) && !looksProxied(req)) {
+            next();
+            return;
+        }
+        const presented = bearerTokenFromHeader(req.get('authorization'));
+        if (presented === null || !timingSafeTokenMatch(presented, apiToken)) {
+            res.status(401).json({
+                error: {
+                    code: 'API_TOKEN_REQUIRED',
+                    message: `Authorization: Bearer <${tokenConfig.tokenEnvVar}> required`,
+                },
+            });
+            return;
+        }
+        next();
+    });
+}
+/**
+ * Builds a bearer gate with **no loopback exemption and no disable flag** — for a daemon whose
+ * threat model is "another process running as the same OS user", not "a remote attacker".
+ *
+ * This is deliberately not {@link registerApiBearerAuthMiddleware}. That gate short-circuits for any
+ * loopback peer before it ever reads the `Authorization` header, which is the right affordance for a
+ * desktop UI or local CLI talking to its own daemon, and a no-op against the threat here: a
+ * `127.0.0.1` bind keeps remote hosts out but does nothing about a co-resident process, and a
+ * sidecar daemon that can start real agent runs and execute real tools is exactly the kind of thing
+ * such a process would want to reach. This gate treats a request from `127.0.0.1` like any other.
+ *
+ * The posture matches `remote-run-events.ts`'s own token gate, which made the same call for the same
+ * reason on a single route; this generalizes it to a whole `/api` surface.
+ *
+ * Fail-closed contract:
+ * - token env var unset/empty -> **503**, never a silent pass-through. A misconfigured daemon
+ *   refuses to serve rather than serving unauthenticated callers.
+ * - missing / malformed / wrong token -> **401**.
+ * - exact match -> `next()`.
+ *
+ * The env var is read on every request rather than captured at factory time: a host that mints a
+ * per-boot token may not have done so yet when its module graph is first evaluated, and re-reading
+ * costs one property lookup.
+ *
+ * @param deps - See {@link StrictBearerTokenDeps}. `tokenEnvVar` is required.
+ * @returns Express middleware. Mount it **unprefixed** — `app.use(handler)` — before any route
+ * registrar and before the JSON body parser, so an unauthenticated caller's body is never parsed.
+ * @complexity O(1) per request plus O(n) in the token length for the constant-time comparison.
+ * @overallScore 95/100 — Medium: mounting under a prefix (`app.use('/api', handler)`) silently breaks
+ * `exemptPaths`. Express strips the mount prefix from `req.path`, so an entry written as a full path
+ * (`/api/delegated-tool-calls`) stops matching and the gate rejects a caller the mount site meant to
+ * exempt. Nothing type-checks that, and the failure is a 401 on a route that is supposed to be open
+ * rather than the reverse — noisy rather than dangerous, but confusing to diagnose. Documented rather
+ * than defended against in code: normalizing `req.baseUrl + req.path` here would silently accept both
+ * mount styles and remove the caller's ability to reason about which paths its entries refer to.
+ */
+export function requireStrictBearerToken(deps) {
+    const { tokenEnvVar } = deps;
+    const env = deps.env ?? process.env;
+    const exempt = new Set(deps.exemptPaths ?? []);
+    return function requireStrictBearerTokenMiddleware(req, res, next) {
+        if (exempt.has(req.path)) {
+            next();
+            return;
+        }
+        const expected = env[tokenEnvVar];
+        if (typeof expected !== 'string' || expected.length === 0) {
+            res.status(503).json({
+                error: {
+                    code: 'API_TOKEN_NOT_CONFIGURED',
+                    message: `${tokenEnvVar} is not set — this daemon refuses to serve unauthenticated callers`,
+                },
+            });
+            return;
+        }
+        // Deliberately no loopback/peer-address exemption — see this function's doc.
+        const presented = bearerTokenFromHeader(req.get('authorization'));
+        if (presented === null || !timingSafeTokenMatch(presented, expected)) {
+            res.status(401).json({
+                error: { code: 'API_TOKEN_REQUIRED', message: `Authorization: Bearer <${tokenEnvVar}> required` },
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * 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 this module's doc for why the origin
+ * daemon's safe-GET exemption for that case was dropped.
+ *
+ * @param app - The Express app to register the gate on.
+ * @param deps - See {@link ApiOriginGuardMiddlewareDeps}.
+ * @returns Nothing. Unlike the bearer-token gate, this always registers its middleware — 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.use('/api', (req, res, next) => {
+        const origin = req.headers.origin;
+        if (origin == null || origin === '') {
+            next();
+            return;
+        }
+        if (origin === 'null') {
+            res.status(403).json({ 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) {
+            res.status(403).json({ 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))) {
+                res.status(403).json({ error: 'Cross-origin requests are not allowed' });
+                return;
+            }
+        }
+        next();
+    });
+}
+//# sourceMappingURL=api-security-middleware.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-security-middleware.js","sourceRoot":"","sources":["../src/api-security-middleware.ts"],"names":[],"mappings":"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"}