@pikku/core 0.12.142 → 0.12.144

package/dist/function/function-runner.js

@@ -1,13 +1,13 @@
 import { beginChanges } from './abort-scope.js';
-import { forwardStepName, isCompensationStepName } from './compensation-name.js';
+import { forwardStepName, isCompensationStepName, } from '../compensation-name.js';
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js';
-import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../wirings/channel/channel-middleware-runner.js';
+import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel-middleware-runner.js';
 import { runPermissions } from '../permissions.js';
 import { withoutSecrets } from '../services/secretless.js';
 import { getCreateWireServices, pikkuState } from '../pikku-state.js';
 import { applyDefaultsFromSchema, coerceTopLevelDataFromSchema, validateSchema, } from '../schema.js';
 import { parseVersionedId } from '../version.js';
-import { PikkuSessionService } from '../services/user-session-service.js';
+import { PikkuSessionService, createFunctionSessionWireProps, } from '../services/user-session-service.js';
 import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js';
 import { verifyScopes } from '../scopes.js';
 import { assertFeatureAvailable } from '../wirings/flag/assert-feature-available.js';
@@ -22,6 +22,13 @@ import { getOrCreatePackageSingletonServices } from '../wirings/addon/addon-runn
 import { resolveAddonAuth, resolveAddonFunctionTarget, resolveAddonScopes, resolveAddonTagMiddleware, } from '../wirings/addon/wire-addon.js';
 import { closeWireServices } from '../utils.js';
 async function resolveSession(wire, singletonServices, sessionService) {
+    // A session middleware established lives on the session service, not on the
+    // transport's snapshot of the wire. Read it from there, so it is what the
+    // function sees and what its user id is resolved from.
+    // knowledge: decisions/security/set-session-persists-and-set-initial-session-does-not.md
+    if (!wire.session && sessionService?.get()) {
+        wire.session = sessionService.get();
+    }
     const pikkuUserId = defaultPikkuUserIdResolver(wire);
     if (pikkuUserId) {
         wire.pikkuUserId = pikkuUserId;
@@ -45,6 +52,15 @@ async function resolveSession(wire, singletonServices, sessionService) {
         sessionService?.setInitial(wire.session);
     }
 }
+/**
+ * Registers a function's config under its id so wirings can run it by name.
+ * Generated code calls this for every function codegen found; an app rarely
+ * needs to. Registering the same id again replaces the earlier config.
+ *
+ * @param funcName - The function id, as it appears in the generated metadata.
+ * @param funcConfig - The object a `pikkuFunc` / `pikkuSessionlessFunc` returned.
+ * @param packageName - The addon package it belongs to; `null` for the app.
+ */
 export const addFunction = (funcName, funcConfig, packageName = null) => {
     pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig);
 };
@@ -52,6 +68,10 @@ export const getFunctionNames = (packageName = null) => {
     const functionsMeta = pikkuState(packageName, 'function', 'meta');
     return Object.keys(functionsMeta);
 };
+/**
+ * Every function id with generated metadata: the app's own, then each addon's
+ * prefixed with the namespace it was wired under (`ns:name`).
+ */
 export const getAllFunctionNames = () => {
     const functions = [];
     const mainFunctionsMeta = pikkuState(null, 'function', 'meta');
@@ -65,6 +85,34 @@ export const getAllFunctionNames = () => {
     }
     return functions;
 };
+/**
+ * Runs one registered function the way every wiring does. Each transport's
+ * runner (HTTP, channel, queue, scheduler, RPC, MCP, CLI, workflow, agent)
+ * ends up here; an app calls it directly only when it is building its own
+ * transport.
+ *
+ * In order, it: resolves the function (falling back from `name@vN` to the
+ * unversioned name, and into an addon for `ns:name`), runs the combined
+ * middleware, resolves the session, enforces auth, `readonly`, scopes and the
+ * feature flag, reads `data()`, applies schema defaults and validation, runs
+ * global and function permissions, builds and finally closes the wire
+ * services, and calls the function. The function and its permissions receive
+ * services whose `secrets` throws on access — they read secrets through the
+ * declared typed wrappers instead.
+ *
+ * @param wireType - The transport, recorded on `wire.wireType` if unset.
+ * @param wireId - The wiring's id (route, queue name, …), recorded on
+ * `wire.wireId` if unset. Middleware registered against it is applied.
+ * @param funcName - The registered function id.
+ * @returns Whatever the function returns.
+ * @throws {MissingSessionError} A session is required and none resolved.
+ * @throws {ReadonlySessionError} A readonly session called a mutating function.
+ * @throws {MissingScopeError} The session lacks a required scope.
+ * @throws {FeatureUnavailableError} The function's feature flag is off.
+ * @throws {ForbiddenError} A permission refused the call.
+ * @throws {Error} The function or its metadata is not registered. Errors thrown
+ * by validation, middleware and the function itself propagate unchanged.
+ */
 export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, wireServices: providedWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, coerceDataFromSchema, wire, sessionService, credentialWireService, packageName = null, addonInstance, }) => {
     wire.wireType ??= wireType;
     wire.wireId ??= wireId;
@@ -204,17 +252,13 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     const executeFunction = async () => {
         await resolveSession(invocationWire, resolvedSingletonServices, sessionService);
         if (sessionService) {
-            invocationWire.session = sessionService.freezeInitial();
-            invocationWire.setSession = (s) => sessionService.set(s);
-            invocationWire.clearSession = () => sessionService.clear();
-            invocationWire.getSession = () => sessionService.get();
-            invocationWire.hasSessionChanged = () => sessionService.sessionChanged;
+            Object.assign(invocationWire, createFunctionSessionWireProps(sessionService));
         }
         const session = invocationWire.session;
         if (funcMeta.sessionless) {
             if (wiringAuth === true ||
                 funcConfig.auth === true ||
-                resolveAddonAuth(packageName, addonInstance?.namespace)) {
+                resolveAddonAuth(funcPackageName, addonInstance?.namespace)) {
                 if (!session) {
                     throw new MissingSessionError('Authentication required');
                 }
@@ -239,7 +283,9 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             invocationWire.beginChanges = () => beginChanges(abortScope);
         }
         // knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
-        const addonScopes = resolveAddonScopes(packageName, addonInstance?.namespace);
+        // The function's package, not the wire's: a `ref('ns:fn')` route stays the
+        // app's, and reading the wire's left it outside the addon's floor.
+        const addonScopes = resolveAddonScopes(funcPackageName, addonInstance?.namespace);
         const functionScopes = funcConfig.scopes ?? funcMeta.scopes;
         verifyScopes(addonScopes.length > 0
             ? [...addonScopes, ...(functionScopes ?? [])]
@@ -330,7 +376,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             }
         }
     };
-    const addonTagMiddleware = resolveAddonTagMiddleware(packageName, addonInstance?.namespace);
+    const addonTagMiddleware = resolveAddonTagMiddleware(funcPackageName, addonInstance?.namespace);
     const allMiddleware = combineMiddleware(wireType, wireId, {
         wireInheritedMiddleware: inheritedMiddleware,
         wireMiddleware: addonTagMiddleware.length > 0

package/dist/function/functions.types.d.ts

@@ -7,15 +7,50 @@ import type { PikkuError } from '../errors/error-handler.js';
 import type { CoreNodeConfig } from '../wirings/node/node.types.js';
 import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js';
 import type { Safe } from '../classification/secret-value.js';
+/**
+ * The body of a function that requires a session: `(services, data, wire)`,
+ * with `wire.session` typed as present. `pikkuFunc` takes one of these; the
+ * runner refuses the call with `MissingSessionError` before the body runs when
+ * there is no session.
+ */
 export type CorePikkuFunction<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Safe<Out>> : Promise<Safe<Out>> | Promise<void>;
+/**
+ * The body of a function that may run without a session, so `wire.session` is
+ * optional. `pikkuSessionlessFunc` takes one of these.
+ */
 export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> = PikkuWire<In, Out, false, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Safe<Out>> : Promise<Safe<Out>> | Promise<void>;
+/**
+ * A permission check: resolves `true` to allow the call. Runs after input
+ * validation, so `data` is the validated input. Its services have no
+ * `secrets`.
+ */
 export type CorePikkuPermission<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
+/**
+ * The object form of {@link pikkuPermission}, for a check that carries a name
+ * or description.
+ */
 export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = {
     func: CorePikkuPermission<In, Services, Wire>;
     name?: string;
     description?: string;
 };
+/**
+ * Declares a permission: an async check that resolves `true` to allow a call
+ * and `false` to refuse it with `ForbiddenError` (403). It receives the
+ * services (without `secrets`), the validated input and the wire.
+ *
+ * Attach it through a function's or wiring's `permissions`: within one group
+ * the keys are alternatives, so the call passes when any key passes, and an
+ * array under a key must pass in full. Global permissions from
+ * `addGlobalPermission` must all pass as well.
+ *
+ * @example snippet: permissionFunction
+ */
 export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'>>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
+/**
+ * A function that takes options and returns a permission, as declared with
+ * {@link pikkuPermissionFactory}.
+ */
 export type CorePikkuPermissionFactory<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
 /**
  * Declares a permission that takes configuration, so one check serves many
@@ -35,7 +70,12 @@ export type CorePikkuApprovalDescription<In = any, Services extends CoreSecretle
  * @example snippet: approvalDescription
  */
 export declare const pikkuApprovalDescription: <In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
+/** A session check: receives the services and the session, never the input. */
 export type CorePikkuAuth<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
+/**
+ * The object form of {@link pikkuAuth}, for a check that carries a name or
+ * description.
+ */
 export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = {
     func: CorePikkuAuth<Services, Session>;
     name?: string;
@@ -50,7 +90,22 @@ export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices
 export type AuthBranded = {
     __pikkuAuth?: true;
 };
+/**
+ * Declares a permission that depends only on the session, not the input. The
+ * resulting permission refuses outright when there is no session, so the
+ * check itself always sees one.
+ *
+ * Because it does not read the input, an agent can evaluate it ahead of time
+ * to decide which tools a session may be offered (see `checkAuthPermissions`);
+ * ordinary permissions are only checked when a tool is actually called.
+ *
+ * @example snippet: shopIsAuthenticated
+ */
 export declare const pikkuAuth: <Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession>(auth: CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>) => CorePikkuPermission<any, Services, any>;
+/**
+ * Permissions keyed by name. The call passes when any key passes (OR); an array
+ * under one key must pass in full (AND).
+ */
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Record<string, PikkuPermission | PikkuPermission[]> | undefined;
 /**
  * A lifecycle hook: same call signature as the function it hangs off, return
@@ -58,6 +113,10 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Re
  * it is never recorded and never replayed.
  */
 export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (services: Services, data: Data, wire: Wire) => Promise<void> | void;
+/**
+ * Everything a function is declared with: its body and the options
+ * `pikkuFunc` / `pikkuSessionlessFunc` accept.
+ */
 export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Scope extends string = string, FeatureFlagName extends string = string> = {
     /** A human name for this function, shown wherever it is listed rather than called. */
     title?: string;

package/dist/function/functions.types.js

@@ -1,3 +1,15 @@
+/**
+ * Declares a permission: an async check that resolves `true` to allow a call
+ * and `false` to refuse it with `ForbiddenError` (403). It receives the
+ * services (without `secrets`), the validated input and the wire.
+ *
+ * Attach it through a function's or wiring's `permissions`: within one group
+ * the keys are alternatives, so the call passes when any key passes, and an
+ * array under a key must pass in full. Global permissions from
+ * `addGlobalPermission` must all pass as well.
+ *
+ * @example snippet: permissionFunction
+ */
 export const pikkuPermission = (permission) => {
     return typeof permission === 'function' ? permission : permission.func;
 };
@@ -18,6 +30,17 @@ export const pikkuPermissionFactory = (factory) => {
 export const pikkuApprovalDescription = (fn) => {
     return fn;
 };
+/**
+ * Declares a permission that depends only on the session, not the input. The
+ * resulting permission refuses outright when there is no session, so the
+ * check itself always sees one.
+ *
+ * Because it does not read the input, an agent can evaluate it ahead of time
+ * to decide which tools a session may be offered (see `checkAuthPermissions`);
+ * ordinary permissions are only checked when a tool is actually called.
+ *
+ * @example snippet: shopIsAuthenticated
+ */
 export const pikkuAuth = (auth) => {
     const fn = typeof auth === 'function' ? auth : auth.func;
     const wrapper = async (services, _data, wire) => {

package/dist/function/list.types.d.ts

@@ -18,6 +18,10 @@ export interface ListInput<F extends Record<string, unknown> = Record<string, ne
     /** Unstructured text search across server-configured fields. */
     search?: string;
 }
+/**
+ * The output a list function returns: one page of rows and the cursor for the
+ * next.
+ */
 export interface ListOutput<Row> {
     rows: Row[];
     /** Null when no more pages. */

package/dist/lifecycle.d.ts

@@ -1,6 +1,17 @@
 import type { CoreSingletonServices, ServerLifecycle } from './types/core.types.js';
 /** Stops addon package services first, then the parent singleton services. */
 export declare const stopSingletonServices: () => Promise<void>;
-/** Wrap server lifecycle hooks so the inspector can discover them. */
+/**
+ * Wrap server lifecycle hooks so the inspector can discover them.
+ *
+ * @example snippet: serverLifecycle
+ */
 export declare const pikkuServerLifecycle: <SS extends CoreSingletonServices = CoreSingletonServices>(lifecycle: ServerLifecycle<SS>) => ServerLifecycle<SS>;
+/**
+ * Calls `run` once when the process receives one of `signals` (default
+ * `SIGINT` and `SIGTERM`); later signals are ignored while it runs. Does
+ * nothing outside Node-like runtimes. It does not exit the process.
+ *
+ * @returns A function that removes the handlers.
+ */
 export declare const onShutdownSignals: (run: (signal: NodeJS.Signals) => void | Promise<void>, signals?: NodeJS.Signals[]) => (() => void);

package/dist/lifecycle.js

@@ -34,8 +34,19 @@ export const stopSingletonServices = async () => {
         await stopService(logger, name, service);
     }
 };
-/** Wrap server lifecycle hooks so the inspector can discover them. */
+/**
+ * Wrap server lifecycle hooks so the inspector can discover them.
+ *
+ * @example snippet: serverLifecycle
+ */
 export const pikkuServerLifecycle = (lifecycle) => lifecycle;
+/**
+ * Calls `run` once when the process receives one of `signals` (default
+ * `SIGINT` and `SIGTERM`); later signals are ignored while it runs. Does
+ * nothing outside Node-like runtimes. It does not exit the process.
+ *
+ * @returns A function that removes the handlers.
+ */
 export const onShutdownSignals = (run, signals = ['SIGINT', 'SIGTERM']) => {
     const proc = typeof process !== 'undefined' ? process : undefined;
     if (!proc?.on)

package/dist/middleware/addon-scope-cap.d.ts

@@ -1,3 +1,7 @@
+/**
+ * The request header naming the addon a call is made on behalf of, read by
+ * {@link addonScopeCap}.
+ */
 export declare const ADDON_HEADER = "x-pikku-addon";
 /**
  * Narrows the session to what an addon is allowed to do. A call that names an

package/dist/middleware/addon-scope-cap.js

@@ -1,6 +1,10 @@
 import { ForbiddenError } from '../errors/errors.js';
 import { intersectScopes } from '../scopes.js';
 import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';
+/**
+ * The request header naming the addon a call is made on behalf of, read by
+ * {@link addonScopeCap}.
+ */
 export const ADDON_HEADER = 'x-pikku-addon';
 /**
  * Narrows the session to what an addon is allowed to do. A call that names an
@@ -16,17 +20,17 @@ export const ADDON_HEADER = 'x-pikku-addon';
  * Register it after the session middleware: it narrows a session that is
  * already resolved, and a call with no session has nothing to narrow.
  */
-export const addonScopeCap = pikkuMiddlewareFactory(({ resolve }) => pikkuMiddleware(async (_services, { http, setSession, getSession }, next) => {
+export const addonScopeCap = pikkuMiddlewareFactory(({ resolve }) => pikkuMiddleware(async (_services, { http, setInitialSession, getSession }, next) => {
     const name = http?.request?.header(ADDON_HEADER);
     const session = await getSession?.();
-    if (!name || !setSession || !session) {
+    if (!name || !setInitialSession || !session) {
         return next();
     }
     const role = await resolve(name);
     if (!role) {
         throw new ForbiddenError(`Unknown addon '${name}'`);
     }
-    await setSession({
+    setInitialSession({
         ...session,
         scopes: intersectScopes(session.scopes, role),
     });

package/dist/middleware/auth-apikey.js

@@ -5,8 +5,8 @@ import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories
  *
  * @example snippet: machineAuth
  */
-export const authAPIKey = pikkuMiddlewareFactory(({ source }) => pikkuMiddleware(async ({ jwt: jwtService }, { http, setSession, session }, next) => {
-    if (!http?.request || !setSession || session) {
+export const authAPIKey = pikkuMiddlewareFactory(({ source }) => pikkuMiddleware(async ({ jwt: jwtService }, { http, setInitialSession, session }, next) => {
+    if (!http?.request || !setInitialSession || session) {
         return next();
     }
     let apiKey = null;
@@ -19,7 +19,7 @@ export const authAPIKey = pikkuMiddlewareFactory(({ source }) => pikkuMiddleware
     if (apiKey && jwtService) {
         const userSession = await jwtService.decode(apiKey);
         if (userSession) {
-            await setSession?.(userSession);
+            setInitialSession?.(userSession);
         }
     }
     return next();

package/dist/middleware/auth-bearer.js

@@ -1,14 +1,6 @@
 import { InvalidSessionError } from '../errors/errors.js';
 import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';
-const constantTimeEqual = (a, b) => {
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
-};
+import { timingSafeStringEqual } from '../utils/hmac.js';
 /**
  * Validates a bearer token: JWT-decoded by default, or compared in constant
  * time against a static `value` or a `secretId` resolved through the secrets
@@ -16,8 +8,8 @@ const constantTimeEqual = (a, b) => {
  *
  * @example snippet: machineAuth
  */
-export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddleware(async ({ jwt: jwtService, secrets }, { http, setSession, session }, next) => {
-    if (!http?.request || !setSession || session) {
+export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddleware(async ({ jwt: jwtService, secrets }, { http, setInitialSession, session }, next) => {
+    if (!http?.request || !setInitialSession || session) {
         return next();
     }
     const authHeader = http.request.header('authorization') ||
@@ -40,7 +32,7 @@ export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddle
                     .catch(() => undefined);
                 expected = stored?.reveal();
             }
-            if (expected && constantTimeEqual(bearerToken, expected)) {
+            if (expected && timingSafeStringEqual(bearerToken, expected)) {
                 userSession = token.userSession;
             }
         }
@@ -48,7 +40,7 @@ export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddle
             userSession = await jwtService.decode(bearerToken);
         }
         if (userSession) {
-            await setSession?.(userSession);
+            setInitialSession?.(userSession);
         }
     }
     return next();

package/dist/middleware/auth-cookie.js

@@ -34,8 +34,8 @@ export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn })
         path: '/',
         ...options,
     };
-    return pikkuMiddleware(async ({ jwt: jwtService, logger }, { http, setSession, getSession, session, hasSessionChanged }, next) => {
-        if (!http?.request || !setSession || session) {
+    return pikkuMiddleware(async ({ jwt: jwtService, logger }, { http, setInitialSession, getSession, session, hasSessionChanged }, next) => {
+        if (!http?.request || !setInitialSession || session) {
             return next();
         }
         const cookieValue = http.request.cookie(name);
@@ -47,7 +47,7 @@ export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn })
             // standard JWT timestamp, so an identity-less token is treated as no
             // session rather than as an authenticated one.
             if (userSession && hasSessionIdentity(userSession)) {
-                await setSession?.(userSession);
+                setInitialSession?.(userSession);
             }
         }
         await next();

package/dist/middleware/middleware-factories.d.ts

@@ -2,7 +2,24 @@ import type { CoreSingletonServices, CoreUserSession } from '../types/core.types
 import type { CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory } from '../wirings/channel/channel.types.js';
 import type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory } from './middleware.types.js';
+/**
+ * Declares middleware that runs around a function: authentication, logging,
+ * headers, rate limits. Takes the middleware itself, or `{ func, name,
+ * description, priority }`; `priority` (default `medium`) orders it among the
+ * other middleware on the same invocation, `highest` outermost.
+ *
+ * The inspector reads the destructured services and wire parameters to know
+ * what the middleware uses, so destructure them rather than taking them whole.
+ *
+ * @example snippet: corsMiddleware
+ */
 export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareConfig<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
+/**
+ * Declares middleware that takes options, so one definition can be wired
+ * several times with different configuration.
+ *
+ * @example snippet: middlewareFactory
+ */
 export declare const pikkuMiddlewareFactory: <In = any>(factory: CorePikkuMiddlewareFactory<In>) => CorePikkuMiddlewareFactory<In>;
 /**
  * Declares middleware for a channel — it runs around the connection and its

package/dist/middleware/middleware-factories.js

@@ -1,3 +1,14 @@
+/**
+ * Declares middleware that runs around a function: authentication, logging,
+ * headers, rate limits. Takes the middleware itself, or `{ func, name,
+ * description, priority }`; `priority` (default `medium`) orders it among the
+ * other middleware on the same invocation, `highest` outermost.
+ *
+ * The inspector reads the destructured services and wire parameters to know
+ * what the middleware uses, so destructure them rather than taking them whole.
+ *
+ * @example snippet: corsMiddleware
+ */
 export const pikkuMiddleware = (middleware) => {
     if (typeof middleware === 'function')
         return middleware;
@@ -7,6 +18,12 @@ export const pikkuMiddleware = (middleware) => {
     }
     return func;
 };
+/**
+ * Declares middleware that takes options, so one definition can be wired
+ * several times with different configuration.
+ *
+ * @example snippet: middlewareFactory
+ */
 export const pikkuMiddlewareFactory = (factory) => {
     return factory;
 };

package/dist/middleware/middleware.types.d.ts

@@ -1,10 +1,20 @@
 import type { CoreSingletonServices, CoreUserSession, PikkuWire } from '../types/core.types.js';
+/**
+ * Middleware around a function invocation: it receives the services and the
+ * wire, and runs the rest of the chain by awaiting `next()`. Not calling `next`
+ * stops the chain, so the function never runs; throwing answers with that
+ * error.
+ */
 export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wires: PikkuWire, next: () => Promise<void>) => Promise<void>;
 /**
  * Execution order: `highest` runs first (outermost in the onion), `lowest`
  * runs last, closest to the function.
  */
 export type MiddlewarePriority = 'highest' | 'high' | 'medium' | 'low' | 'lowest';
+/**
+ * The object form of {@link pikkuMiddleware}, for middleware that carries a
+ * name, description or priority.
+ */
 export type CorePikkuMiddlewareConfig<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = {
     func: CorePikkuMiddleware<SingletonServices, UserSession>;
     name?: string;
@@ -12,8 +22,21 @@ export type CorePikkuMiddlewareConfig<SingletonServices extends CoreSingletonSer
     /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
     priority?: MiddlewarePriority;
 };
+/**
+ * A function that takes options and returns middleware, as declared with
+ * {@link pikkuMiddlewareFactory}.
+ */
 export type CorePikkuMiddlewareFactory<In = any, SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>;
+/**
+ * A list of middleware, or middleware factories, registered together against
+ * a tag or route.
+ */
 export type CorePikkuMiddlewareGroup<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = Array<CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>>;
+/**
+ * How codegen records where a piece of inherited middleware comes from: an
+ * HTTP route pattern, a tag, or a named wire-level middleware.
+ * @internal
+ */
 export type MiddlewareMetadata = {
     type: 'http';
     route: string;

package/dist/middleware/remote-auth.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Authenticates calls between deployments of the same app, on the generated
+ * remote-RPC route. Once `PIKKU_REMOTE_SECRET` is set it requires a
+ * `Bearer` JWT with audience `pikku-remote`; a token bound to a function (`fn`)
+ * is only accepted on that function's `/remote/rpc/<fn>` path, and any session
+ * it carries is decrypted with the secret and set on the wire.
+ *
+ * Without the secret it lets non-remote paths through and refuses
+ * `/remote/rpc/*`, so the remote surface fails closed.
+ *
+ * @throws {UnauthorizedError} On a missing, malformed, mis-addressed or
+ * undecryptable token.
+ * @throws {WeakKeyMaterialError} When the secret is too short to use.
+ * @throws {Error} When the secret is set but no JWT service is configured.
+ */
 export declare const pikkuRemoteAuthMiddleware: import("./middleware.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {

package/dist/middleware/remote-auth.js

@@ -10,7 +10,22 @@ const REMOTE_RPC_PREFIX = '/remote/rpc/';
  * past the trust gate and the token's `fn` binding while still being dispatched.
  */
 const isRemoteRpcPath = (path) => path.toLowerCase().startsWith(REMOTE_RPC_PREFIX);
-export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setSession }, next) => {
+/**
+ * Authenticates calls between deployments of the same app, on the generated
+ * remote-RPC route. Once `PIKKU_REMOTE_SECRET` is set it requires a
+ * `Bearer` JWT with audience `pikku-remote`; a token bound to a function (`fn`)
+ * is only accepted on that function's `/remote/rpc/<fn>` path, and any session
+ * it carries is decrypted with the secret and set on the wire.
+ *
+ * Without the secret it lets non-remote paths through and refuses
+ * `/remote/rpc/*`, so the remote surface fails closed.
+ *
+ * @throws {UnauthorizedError} On a missing, malformed, mis-addressed or
+ * undecryptable token.
+ * @throws {WeakKeyMaterialError} When the secret is too short to use.
+ * @throws {Error} When the secret is set but no JWT service is configured.
+ */
+export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setInitialSession }, next) => {
     if (!http?.request || !secrets) {
         return next();
     }
@@ -58,8 +73,8 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     if (payload?.session) {
         try {
             const decrypted = await decryptWithKeyMaterial('PIKKU_REMOTE_SECRET', secret, REMOTE_SESSION_INFO, payload.session);
-            if (decrypted?.session && setSession) {
-                await setSession(decrypted.session);
+            if (decrypted?.session && setInitialSession) {
+                setInitialSession(decrypted.session);
             }
         }
         catch {

package/dist/middleware/remote-jobs-secret.js

@@ -1,15 +1,7 @@
 import { UnauthorizedError } from '../errors/errors.js';
 import { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, } from '../services/remote-jobs.js';
 import { pikkuMiddleware } from './middleware-factories.js';
-const constantTimeEqual = (a, b) => {
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
-};
+import { timingSafeStringEqual } from '../utils/hmac.js';
 /**
  * Guards the remote job inbox. Fails closed: an unset secret rejects every
  * caller, so the routes are never open just because the deployment forgot to
@@ -20,7 +12,7 @@ export const remoteJobsSecret = pikkuMiddleware(async ({ variables }, { http },
     const provided = http?.request?.header(REMOTE_JOBS_SECRET_HEADER);
     if (!expected ||
         typeof provided !== 'string' ||
-        !constantTimeEqual(provided, expected)) {
+        !timingSafeStringEqual(provided, expected)) {
         throw new UnauthorizedError('invalid dispatch secret');
     }
     return next();

package/dist/middleware-runner.d.ts

@@ -1,5 +1,12 @@
 import type { PikkuWiringTypes } from './types/core.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup, MiddlewareMetadata } from './middleware/middleware.types.js';
+/**
+ * Runs `middlewares` as an onion around `main`, ordered by priority (stable
+ * within a priority), and returns `main`'s result. A middleware that does not
+ * call `next` stops the chain: `main` is never run and the result is
+ * `undefined`.
+ * @internal
+ */
 export declare const runMiddleware: <Middleware extends CorePikkuMiddleware<any, any>>(services: Parameters<Middleware>[0], wire: Parameters<Middleware>[1], middlewares: readonly Middleware[], main?: () => Promise<unknown>) => Promise<unknown>;
 /**
  * Registers tag-scoped middleware for any wiring carrying the tag. Wrap in a