@pikku/core 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 ## 0.12.0
 
+## 0.12.2
+
+### Patch Changes
+
+- cc4c9e9: Add gateway meta-wiring for messaging platforms:
+
+  - New `wireGateway()` API with three transport types: webhook, websocket, listener
+  - `GatewayAdapter` interface for platform-specific parse/send logic
+  - `PikkuGateway` wire object (`wire.gateway`) with senderId, platform, and send()
+  - `GatewayService` interface and `LocalGatewayService` for listener gateway lifecycle
+  - `createListenerMessageHandler()` helper for building listener message callbacks
+  - Add `'gateway'` to `PikkuWiringTypes` and `gateway` to `PikkuWire`
+  - Add `gateway` state block to `PikkuPackageState`
+
+- 3e04565: chore: update dependencies to latest minor/patch versions
+
+## 0.12.1
+
+### Patch Changes
+
+- 62a8725: Rename 'external' to 'addon' throughout the codebase. All types, functions, config keys, and CLI options previously named `external` or `External` are now named `addon` or `Addon` (e.g. `ExternalPackageConfig` → `AddonConfig`, `externalPackages` → `addons`, `function-external` → `function-addon`).
+- a3bdb0d: Add AI middleware hooks for per-tool-call lifecycle and post-step observability:
+
+  - `beforeToolCall` / `afterToolCall`: per-tool-call hooks for logging, caching, input sanitization, and result transformation
+  - `afterStep`: post-step observation hook with full step context (text, toolCalls, toolResults, usage, finishReason)
+  - `onError`: error-specific hook for alerting and diagnostics (non-throwing, won't affect error flow)
+
+- e0349ff: Fix critical security vulnerability in channel message handler: `validateAuth` was being called with `channelHandler` (always truthy) instead of the actual user session, meaning auth checks always passed and unauthenticated clients could send messages to protected channels. Also fix an information disclosure issue where the full channel config object was being logged on unhandled messages.
+- 62a8725: Internalize singleton services management in the serverless channel runner, consistent with how other runners handle it. `createWireServices` and `singletonServices` no longer need to be passed explicitly to serverless channel runner calls.
+- e04531f: Security hardening: improve CORS handling, redirect validation, and error logging in the HTTP runner. Export additional internal utilities needed by native runtime adapters.
+- 62a8725: Fix security issue in `function-runner`: functions declared with `pikkuFunc` (which always require a session) now always throw `ForbiddenError` when called without a session, even if the wiring has `auth: false`. Previously a misconfigured wiring could bypass authentication entirely — the runner only logged a warning instead of blocking the call.
+- a83efb8: Handle OPTIONS preflight requests automatically in fetchData when no explicit OPTIONS route is matched. Runs global HTTP middleware (e.g. CORS) and returns 204. Remove redundant startWorkflowRun and streamAgentRun pass-through functions from addon-console.
+- 8eed717: Add `readonly` flag to function config and runtime enforcement. Functions can be marked `readonly: true` in their config. At runtime, if a session has `readonly: true`, only functions marked as readonly can be called — otherwise a `ReadonlySessionError` (403) is thrown.
+- 62a8725: `pikku versions check` now prints rich, human-readable output for all contract version errors instead of raw error codes. Each error type (PKU861–PKU865) shows the function name, separate input/output schema hashes with a `prev → current` arrow, and clear next-step instructions.
+
+  The version manifest now stores separate `inputHash` and `outputHash` per version entry (backward-compatible — old string-hash manifests still load and validate correctly). `VersionValidateError` gains optional detail fields (`functionKey`, `version`, `previousInputHash`, `currentInputHash`, `previousOutputHash`, `currentOutputHash`, `nextVersion`, `latestVersion`, `expectedNextVersion`) for use by tooling.
+
+- 62a8725: Replace config-based addon declarations with the new `wireAddon()` code-based API. Addons are now declared directly in wiring files using `wireAddon({ name, package, rpcEndpoint?, auth?, tags? })` instead of the `addons` field in `pikku.config.json`. The inspector reads these declarations from the TypeScript AST at build time.
+- 62a8725: Add `secretOverrides` and `variableOverrides` support to `wireAddon()`. These optional maps allow an app to remap an addon's secret/variable keys to its own names (e.g. `secretOverrides: { SENDGRID_API_KEY: 'MY_EMAIL_API_KEY' }`). The inspector validates that all override keys exist in the app's own secrets/variables definitions.
+
 ### New Features
 
 - AI agents with `pikkuAIAgent()` — define agents with tools, sub-agents, memory, structured output, and streaming via SSE

package/dist/errors/errors.d.ts

@@ -42,6 +42,12 @@ export declare class PaymentRequiredError extends PikkuError {
  */
 export declare class ForbiddenError extends PikkuError {
 }
+/**
+ * The session is readonly and cannot access a non-readonly function.
+ * @group Error
+ */
+export declare class ReadonlySessionError extends PikkuError {
+}
 /**
  * The request was made from an origin that is not permitted to access this resource.
  * @group Error

package/dist/errors/errors.js

@@ -72,6 +72,16 @@ addError(ForbiddenError, {
     status: 403,
     message: 'The client does not have permission to access the requested resource.',
 });
+/**
+ * The session is readonly and cannot access a non-readonly function.
+ * @group Error
+ */
+export class ReadonlySessionError extends PikkuError {
+}
+addError(ReadonlySessionError, {
+    status: 403,
+    message: 'The session is readonly and cannot access this function.',
+});
 /**
  * The request was made from an origin that is not permitted to access this resource.
  * @group Error

package/dist/errors/index.d.ts

@@ -1 +1,2 @@
 export * from './errors.js';
+export { PikkuError, addError, addErrors } from './error-handler.js';

package/dist/errors/index.js

@@ -1 +1,2 @@
 export * from './errors.js';
+export { PikkuError, addError, addErrors } from './error-handler.js';

package/dist/function/function-runner.d.ts

@@ -1,7 +1,7 @@
-import { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
+import type { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
-import { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
-import { SessionService } from '../services/user-session-service.js';
+import type { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
+import type { SessionService } from '../services/user-session-service.js';
 export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
 export declare const getFunctionNames: (packageName?: string | null) => string[];
 export declare const getAllFunctionNames: () => string[];

package/dist/function/function-runner.js

@@ -4,15 +4,15 @@ import { runPermissions } from '../permissions.js';
 import { pikkuState } from '../pikku-state.js';
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js';
 import { parseVersionedId } from '../version.js';
-import { createFunctionSessionWireProps, } from '../services/user-session-service.js';
-import { ForbiddenError } from '../errors/errors.js';
+import { createFunctionSessionWireProps } from '../services/user-session-service.js';
+import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { closeWireServices } from '../utils.js';
 /**
- * Get or create singleton services for an external package.
+ * Get or create singleton services for an addon package.
  * Services are cached in pikkuState to avoid recreation on each call.
  *
- * @param packageName - The external package name
+ * @param packageName - The addon package name
  * @param parentServices - The parent/caller's singleton services (used as base)
  * @returns The package's singleton services
  */
@@ -50,8 +50,8 @@ export const getAllFunctionNames = () => {
     const functions = [];
     const mainFunctionsMeta = pikkuState(null, 'function', 'meta');
     functions.push(...Object.keys(mainFunctionsMeta));
-    const externalPackages = pikkuState(null, 'rpc', 'externalPackages');
-    for (const [namespace, config] of externalPackages) {
+    const addons = pikkuState(null, 'rpc', 'addons');
+    for (const [namespace, config] of addons) {
         const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta');
         for (const funcName of Object.keys(packageFunctionsMeta)) {
             functions.push(`${namespace}:${funcName}`);
@@ -71,11 +71,8 @@ export const runPikkuFuncDirectly = async (funcName, allServices, wire, data, us
     return (await funcConfig.func(allServices, data, wireWithSession));
 };
 export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], wire, sessionService, packageName = null, }) => {
-    wire = {
-        ...wire,
-        wireType: wire.wireType ?? wireType,
-        wireId: wire.wireId ?? wireId,
-    };
+    wire.wireType ??= wireType;
+    wire.wireId ??= wireId;
     const funcMap = pikkuState(packageName, 'function', 'functions');
     let funcConfig = funcMap.get(funcName);
     const allMeta = pikkuState(packageName, 'function', 'meta');
@@ -96,7 +93,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     if (!funcMeta) {
         throw new Error(`Function meta not found: ${funcName}`);
     }
-    // For external packages, get or create their singleton services
+    // For addon packages, get or create their singleton services
     const resolvedSingletonServices = packageName
         ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
         : singletonServices;
@@ -117,20 +114,26 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         ? wrapChannelWithMiddleware(wire, resolvedSingletonServices, allChannelMiddleware)
         : wire;
     // Convert tags to PermissionMetadata and merge with inheritedPermissions
-    const mergedInheritedPermissions = [
-        ...(inheritedPermissions || []),
-        ...(tags?.map((tag) => ({ type: 'tag', tag })) || []),
-    ];
+    let mergedInheritedPermissions;
+    if (tags && tags.length > 0) {
+        mergedInheritedPermissions = [
+            ...(inheritedPermissions || []),
+            ...tags.map((tag) => ({ type: 'tag', tag })),
+        ];
+    }
+    else {
+        mergedInheritedPermissions = inheritedPermissions || [];
+    }
     // Helper function to run permissions and execute the function
     const executeFunction = async () => {
-        const functionWireProps = sessionService
-            ? createFunctionSessionWireProps(sessionService)
-            : undefined;
-        const wireWithSession = {
-            ...resolvedWire,
-            ...functionWireProps,
-        };
-        const session = wireWithSession.session;
+        if (sessionService) {
+            resolvedWire.session = sessionService.freezeInitial();
+            resolvedWire.setSession = (s) => sessionService.set(s);
+            resolvedWire.clearSession = () => sessionService.clear();
+            resolvedWire.getSession = () => sessionService.get();
+            resolvedWire.hasSessionChanged = () => sessionService.sessionChanged;
+        }
+        const session = resolvedWire.session;
         if (funcMeta.sessionless) {
             if (wiringAuth === true || funcConfig.auth === true) {
                 if (!session) {
@@ -142,7 +145,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             if (wiringAuth === false || funcConfig.auth === false) {
                 resolvedSingletonServices.logger.warn(`Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`);
             }
-            else if (!session) {
+            if (!session) {
                 throw new ForbiddenError('Authentication required');
             }
         }
@@ -155,6 +158,9 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 }
             }
         }
+        if (session?.readonly && !funcMeta.readonly) {
+            throw new ReadonlySessionError();
+        }
         // Evaluate the data from the lazy function
         const actualData = await data();
         // Validate and coerce data if schema is defined
@@ -167,29 +173,45 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName);
             }
         }
-        await runPermissions(wireType, wireId, {
-            wireInheritedPermissions: mergedInheritedPermissions,
-            wirePermissions: wirePermissions,
-            funcInheritedPermissions: funcMeta.permissions,
-            funcPermissions: funcConfig.permissions,
-            services: resolvedSingletonServices,
-            wire: { ...wireWithSession, rpc: undefined },
-            data: actualData,
-            packageName,
-        });
-        const wireServices = await resolvedCreateWireServices?.(resolvedSingletonServices, wireWithSession);
-        try {
-            const services = { ...resolvedSingletonServices, ...wireServices };
-            const rpc = rpcService.getContextRPCService(services, wireWithSession, {
-                sessionService,
+        if (mergedInheritedPermissions.length > 0 ||
+            wirePermissions ||
+            funcMeta.permissions ||
+            funcConfig.permissions) {
+            await runPermissions(wireType, wireId, {
+                wireInheritedPermissions: mergedInheritedPermissions,
+                wirePermissions: wirePermissions,
+                funcInheritedPermissions: funcMeta.permissions,
+                funcPermissions: funcConfig.permissions,
+                services: resolvedSingletonServices,
+                wire: resolvedWire,
+                data: actualData,
+                packageName,
             });
-            return await funcConfig.func(services, actualData, {
-                ...wireWithSession,
-                rpc,
+        }
+        const wireServices = await resolvedCreateWireServices?.(resolvedSingletonServices, resolvedWire);
+        try {
+            const services = wireServices && Object.keys(wireServices).length > 0
+                ? { ...resolvedSingletonServices, ...wireServices }
+                : resolvedSingletonServices;
+            Object.defineProperty(resolvedWire, 'rpc', {
+                get() {
+                    const rpc = rpcService.getContextRPCService(services, resolvedWire, {
+                        sessionService,
+                    });
+                    Object.defineProperty(resolvedWire, 'rpc', {
+                        value: rpc,
+                        writable: true,
+                        configurable: true,
+                    });
+                    return rpc;
+                },
+                configurable: true,
+                enumerable: true,
             });
+            return await funcConfig.func(services, actualData, resolvedWire);
         }
         finally {
-            if (wireServices) {
+            if (wireServices && Object.keys(wireServices).length > 0) {
                 await closeWireServices(resolvedSingletonServices.logger, wireServices);
             }
         }

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

@@ -122,6 +122,7 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     expose?: boolean;
     remote?: boolean;
     mcp?: boolean;
+    readonly?: boolean;
     requiresApproval?: boolean;
     func: PikkuFunction;
     auth?: boolean;

package/dist/handle-error.d.ts

@@ -1,5 +1,5 @@
-import { Logger } from './services/logger.js';
-import { PikkuHTTP } from './wirings/http/http.types.js';
+import type { Logger } from './services/logger.js';
+import type { PikkuHTTP } from './wirings/http/http.types.js';
 /**
  * Handle errors that occur during route processing
  *

package/dist/handle-error.js

@@ -31,12 +31,12 @@ export const handleHTTPError = (e, http, trackerId, logger, logWarningsForStatus
             if (trackerId) {
                 logger.warn(`Warning id: ${trackerId}`);
             }
-            logger.warn(e);
+            logger.warn(e instanceof Error ? e.message : e);
         }
     }
     else {
         // Handle unexpected errors
-        logger.error(e);
+        logger.error(e instanceof Error ? e.message : e);
         http?.response?.status(500);
         if (trackerId) {
             logger.warn(`Error id: ${trackerId}`);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module @pikku/core
  */
-export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, CreateSingletonServices, CreateWireServices, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
+export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
 export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, } from './function/functions.types.js';
@@ -10,7 +10,6 @@ export { PikkuRequest } from './pikku-request.js';
 export { getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
 export type { RelativeTimeInput } from './time-utils.js';
 export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';
-export { pikkuState, initializePikkuState, resetPikkuState, addPackageServiceFactories, getPikkuMetaDir, } from './pikku-state.js';
 export { runPikkuFunc } from './function/function-runner.js';
 export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js';
 export { fetch } from './wirings/http/http-runner.js';
@@ -26,9 +25,12 @@ export type { HTTPMethod } from './wirings/http/http.types.js';
 export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { workflow as wireWorkflow } from './wirings/workflow/workflow-helpers.js';
+export { wireAddon } from './wirings/rpc/wire-addon.js';
+export type { WireAddonConfig } from './wirings/rpc/wire-addon.js';
 export type { PikkuPackageState } from './types/state.types.js';
 export { runMiddleware, addMiddleware } from './middleware-runner.js';
 export { addPermission } from './permissions.js';
 export { isSerializable, stopSingletonServices } from './utils.js';
-export { type ScheduledTaskInfo, type ScheduledTaskSummary, type SchedulerRuntimeHandlers, } from './services/scheduler-service.js';
+export { getSingletonServices, getCreateWireServices } from './pikku-state.js';
+export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';
 export { SchedulerService } from './services/scheduler-service.js';

package/dist/index.js

@@ -4,7 +4,6 @@ export { addFunction, getAllFunctionNames } from './function/index.js';
 export { PikkuRequest } from './pikku-request.js';
 export { getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
 export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';
-export { pikkuState, initializePikkuState, resetPikkuState, addPackageServiceFactories, getPikkuMetaDir, } from './pikku-state.js';
 export { runPikkuFunc } from './function/function-runner.js';
 export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js';
 export { fetch } from './wirings/http/http-runner.js';
@@ -14,7 +13,9 @@ export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js';
 export { NotFoundError } from './errors/errors.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { workflow as wireWorkflow } from './wirings/workflow/workflow-helpers.js';
+export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { runMiddleware, addMiddleware } from './middleware-runner.js';
 export { addPermission } from './permissions.js';
 export { isSerializable, stopSingletonServices } from './utils.js';
+export { getSingletonServices, getCreateWireServices } from './pikku-state.js';
 export { SchedulerService } from './services/scheduler-service.js';

package/dist/internal.d.ts

@@ -0,0 +1,3 @@
+export { pikkuState, resetPikkuState } from './pikku-state.js';
+export { httpRouter } from './wirings/http/routers/http-router.js';
+export type { CreateSingletonServices, CreateWireServices, } from './types/core.types.js';

package/dist/internal.js

@@ -0,0 +1,2 @@
+export { pikkuState, resetPikkuState } from './pikku-state.js';
+export { httpRouter } from './wirings/http/routers/http-router.js';

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

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../types/core.types.js';
+import type { CoreUserSession } from '../types/core.types.js';
 /**
  * Bearer token middleware that extracts and validates tokens from the Authorization header.
  *

package/dist/middleware/auth-bearer.js

@@ -1,5 +1,5 @@
 import { InvalidSessionError } from '../errors/errors.js';
-import { pikkuMiddleware, pikkuMiddlewareFactory, } from '../types/core.types.js';
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js';
 /**
  * Bearer token middleware that extracts and validates tokens from the Authorization header.
  *

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

@@ -1,5 +1,5 @@
-import { SerializeOptions } from 'cookie';
-import { RelativeTimeInput } from '../time-utils.js';
+import type { SerializeOptions } from 'cookie';
+import type { RelativeTimeInput } from '../time-utils.js';
 /**
  * Cookie-based session middleware that uses JWT for encoding/decoding session data.
  *

package/dist/middleware/auth-cookie.js

@@ -1,5 +1,5 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js';
-import { getRelativeTimeOffsetFromNow, } from '../time-utils.js';
+import { getRelativeTimeOffsetFromNow } from '../time-utils.js';
 /**
  * Cookie-based session middleware that uses JWT for encoding/decoding session data.
  *

package/dist/middleware/cors.d.ts

@@ -4,7 +4,7 @@
  * Sets appropriate CORS headers on all responses and short-circuits OPTIONS
  * preflight requests with a 204 No Content response.
  *
- * @param options.origin - Allowed origin(s). Use `'*'` for any origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
+ * @param options.origin - Allowed origin(s). Use `'*'` for any origin, `true` to reflect the request origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
  * @param options.methods - Allowed HTTP methods. Defaults to common methods.
  * @param options.headers - Allowed request headers. Defaults to common headers.
  * @param options.credentials - Whether to allow credentials. Defaults to `false`.
@@ -34,7 +34,7 @@
  * ```
  */
 export declare const cors: import("../types/core.types.js").CorePikkuMiddlewareFactory<{
-    origin?: string | string[];
+    origin?: string | string[] | true;
     methods?: string[];
     headers?: string[];
     credentials?: boolean;

package/dist/middleware/cors.js

@@ -5,7 +5,7 @@ import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
  * Sets appropriate CORS headers on all responses and short-circuits OPTIONS
  * preflight requests with a 204 No Content response.
  *
- * @param options.origin - Allowed origin(s). Use `'*'` for any origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
+ * @param options.origin - Allowed origin(s). Use `'*'` for any origin, `true` to reflect the request origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
  * @param options.methods - Allowed HTTP methods. Defaults to common methods.
  * @param options.headers - Allowed request headers. Defaults to common headers.
  * @param options.credentials - Whether to allow credentials. Defaults to `false`.
@@ -34,40 +34,48 @@ import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
  * ])
  * ```
  */
-export const cors = pikkuMiddlewareFactory(({ origin = '*', methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], headers = ['Content-Type', 'Authorization', 'x-api-key'], credentials = false, maxAge = 86400, } = {}) => pikkuMiddleware({
-    name: 'CORS',
-    description: 'Handles cross-origin requests including OPTIONS preflight',
-    func: async (_services, wires, next) => {
-        const request = wires.http?.request;
-        const response = wires.http?.response;
-        if (!request || !response) {
+export const cors = pikkuMiddlewareFactory(({ origin = '*', methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], headers = ['Content-Type', 'Authorization', 'x-api-key'], credentials = false, maxAge = 86400, } = {}) => {
+    if (origin === '*' && credentials) {
+        throw new Error('CORS misconfiguration: wildcard origin (*) cannot be used with credentials: true');
+    }
+    return pikkuMiddleware({
+        name: 'CORS',
+        description: 'Handles cross-origin requests including OPTIONS preflight',
+        func: async (_services, wires, next) => {
+            const request = wires.http?.request;
+            const response = wires.http?.response;
+            if (!request || !response) {
+                return next();
+            }
+            const requestOrigin = request.header('origin');
+            let allowedOrigin;
+            if (origin === true) {
+                allowedOrigin = requestOrigin || '*';
+            }
+            else if (Array.isArray(origin)) {
+                allowedOrigin =
+                    requestOrigin && origin.includes(requestOrigin)
+                        ? requestOrigin
+                        : origin[0];
+            }
+            else {
+                allowedOrigin = origin;
+            }
+            response.header('Access-Control-Allow-Origin', allowedOrigin);
+            response.header('Access-Control-Allow-Methods', methods.join(', '));
+            response.header('Access-Control-Allow-Headers', headers.join(', '));
+            if (credentials) {
+                response.header('Access-Control-Allow-Credentials', 'true');
+            }
+            if (origin === true || Array.isArray(origin)) {
+                response.header('Vary', 'Origin');
+            }
+            if (request.method() === 'options') {
+                response.header('Access-Control-Max-Age', String(maxAge));
+                response.status(204).json(undefined);
+                return;
+            }
             return next();
-        }
-        const requestOrigin = request.header('origin');
-        let allowedOrigin;
-        if (Array.isArray(origin)) {
-            allowedOrigin =
-                requestOrigin && origin.includes(requestOrigin)
-                    ? requestOrigin
-                    : origin[0];
-        }
-        else {
-            allowedOrigin = origin;
-        }
-        response.header('Access-Control-Allow-Origin', allowedOrigin);
-        response.header('Access-Control-Allow-Methods', methods.join(', '));
-        response.header('Access-Control-Allow-Headers', headers.join(', '));
-        if (credentials) {
-            response.header('Access-Control-Allow-Credentials', 'true');
-        }
-        if (Array.isArray(origin)) {
-            response.header('Vary', 'Origin');
-        }
-        if (request.method() === 'options') {
-            response.header('Access-Control-Max-Age', String(maxAge));
-            response.status(204).json(undefined);
-            return;
-        }
-        return next();
-    },
-}));
+        },
+    });
+});

package/dist/middleware-runner.d.ts

@@ -1,4 +1,4 @@
-import { CoreSingletonServices, PikkuWire, CorePikkuMiddleware, CorePikkuMiddlewareGroup, PikkuWiringTypes, MiddlewareMetadata } from './types/core.types.js';
+import type { CoreSingletonServices, PikkuWire, CorePikkuMiddleware, CorePikkuMiddlewareGroup, PikkuWiringTypes, MiddlewareMetadata } from './types/core.types.js';
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *

package/dist/middleware-runner.js

@@ -96,6 +96,7 @@ const middlewareCache = {
     agent: {},
     cli: {},
     workflow: {},
+    gateway: {},
 };
 /**
  * Combines wiring-specific middleware with function-level middleware.

package/dist/permissions.d.ts

@@ -1,5 +1,5 @@
-import { CoreServices, PikkuWiringTypes, PermissionMetadata, PikkuWire } from './types/core.types.js';
-import { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
+import type { CoreServices, PikkuWiringTypes, PermissionMetadata, PikkuWire } from './types/core.types.js';
+import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 /**
  * Adds global permissions for a specific tag.
  *

package/dist/permissions.js

@@ -99,6 +99,7 @@ const combinedPermissionsCache = {
     agent: {},
     cli: {},
     workflow: {},
+    gateway: {},
 };
 /**
  * Combines wiring-specific permissions with function-level permissions.

package/dist/pikku-state.d.ts

@@ -1,11 +1,10 @@
-import { PikkuPackageState } from './index.js';
-declare global {
-    var pikkuState: Map<string, PikkuPackageState> | undefined;
-}
+import type { PikkuPackageState } from './index.js';
+import type { CoreSingletonServices, CreateWireServices } from './types/core.types.js';
+export declare const getAllPackageStates: () => Map<string, PikkuPackageState>;
 /**
  * Get or set package-scoped pikku state
  *
- * @param packageName - Package name (null for main package, '@scope/package' for external packages)
+ * @param packageName - Package name (null for main package, '@scope/package' for addon packages)
  * @param type - State category (function, rpc, http, etc.)
  * @param content - Content key within the category
  * @param value - Optional value to set
@@ -15,7 +14,7 @@ declare global {
  * // Main package
  * pikkuState(null, 'function', 'functions').get(funcName)
  *
- * // External package
+ * // Addon package
  * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
  */
 export declare const pikkuState: <Type extends keyof PikkuPackageState, Content extends keyof PikkuPackageState[Type]>(packageName: string | null, type: Type, content: Content, value?: PikkuPackageState[Type][Content]) => PikkuPackageState[Type][Content];
@@ -25,11 +24,13 @@ export declare const pikkuState: <Type extends keyof PikkuPackageState, Content
 export declare const initializePikkuState: (packageName: string) => void;
 export declare const resetPikkuState: () => void;
 export declare const getPikkuMetaDir: (packageName?: string | null) => string | null;
+export declare const getSingletonServices: () => CoreSingletonServices;
+export declare const getCreateWireServices: () => CreateWireServices | undefined;
 /**
- * Register service factories for an external package.
+ * Register service factories for an addon package.
  * These factories are used to create services when the package's functions are invoked.
  *
- * @param packageName - The package name (e.g., '@pikku/templates-function-external')
+ * @param packageName - The package name (e.g., '@pikku/templates-function-addon')
  * @param factories - The service factory functions
  */
 export declare const addPackageServiceFactories: (packageName: string, factories: NonNullable<PikkuPackageState["package"]["factories"]>) => void;