@pikku/core 0.11.2 → 0.12.1

package/dist/middleware/cors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CORS middleware that handles cross-origin requests including OPTIONS preflight.
+ *
+ * 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, `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`.
+ * @param options.maxAge - Preflight cache duration in seconds. Defaults to `86400` (24 hours).
+ *
+ * @example
+ * ```typescript
+ * import { cors } from '@pikku/core/middleware'
+ *
+ * // Allow all origins
+ * addHTTPMiddleware('*', [cors()])
+ *
+ * // Specific origin with credentials
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: 'https://app.example.com',
+ *     credentials: true,
+ *   })
+ * ])
+ *
+ * // Multiple origins
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   })
+ * ])
+ * ```
+ */
+export declare const cors: import("../types/core.types.js").CorePikkuMiddlewareFactory<{
+    origin?: string | string[] | true;
+    methods?: string[];
+    headers?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}, import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../services/logger.js").LogLevel;
+    secrets?: {};
+    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+}>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/cors.js

@@ -0,0 +1,81 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js';
+/**
+ * CORS middleware that handles cross-origin requests including OPTIONS preflight.
+ *
+ * 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, `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`.
+ * @param options.maxAge - Preflight cache duration in seconds. Defaults to `86400` (24 hours).
+ *
+ * @example
+ * ```typescript
+ * import { cors } from '@pikku/core/middleware'
+ *
+ * // Allow all origins
+ * addHTTPMiddleware('*', [cors()])
+ *
+ * // Specific origin with credentials
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: 'https://app.example.com',
+ *     credentials: true,
+ *   })
+ * ])
+ *
+ * // Multiple origins
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   })
+ * ])
+ * ```
+ */
+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();
+        },
+    });
+});

package/dist/middleware/index.d.ts

@@ -1,3 +1,5 @@
-export * from './auth-apikey.js';
-export * from './auth-cookie.js';
-export * from './auth-bearer.js';
+export { authAPIKey } from './auth-apikey.js';
+export { authCookie } from './auth-cookie.js';
+export { authBearer } from './auth-bearer.js';
+export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
+export { cors } from './cors.js';

package/dist/middleware/index.js

@@ -1,3 +1,5 @@
-export * from './auth-apikey.js';
-export * from './auth-cookie.js';
-export * from './auth-bearer.js';
+export { authAPIKey } from './auth-apikey.js';
+export { authCookie } from './auth-cookie.js';
+export { authBearer } from './auth-bearer.js';
+export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
+export { cors } from './cors.js';

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

@@ -0,0 +1,5 @@
+export declare const pikkuRemoteAuthMiddleware: import("../types/core.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../services/logger.js").LogLevel;
+    secrets?: {};
+    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+}>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/remote-auth.js

@@ -0,0 +1,55 @@
+import { UnauthorizedError } from '../errors/errors.js';
+import { pikkuMiddleware } from '../types/core.types.js';
+import { decryptJSON } from '../crypto-utils.js';
+export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setSession }, next) => {
+    if (!http?.request || !secrets) {
+        return next();
+    }
+    let secret;
+    try {
+        secret = await secrets.getSecret('PIKKU_REMOTE_SECRET');
+    }
+    catch {
+        return next();
+    }
+    if (!jwt) {
+        throw new Error('PIKKU_REMOTE_SECRET set but JWT service missing');
+    }
+    const authHeader = http.request.header('authorization') ||
+        http.request.header('Authorization');
+    if (!authHeader) {
+        throw new UnauthorizedError();
+    }
+    const [scheme, token] = authHeader.split(' ');
+    if (scheme !== 'Bearer' || !token) {
+        throw new UnauthorizedError();
+    }
+    let payload;
+    try {
+        payload = await jwt.decode(token);
+    }
+    catch {
+        throw new UnauthorizedError();
+    }
+    if (payload?.aud !== 'pikku-remote') {
+        throw new UnauthorizedError();
+    }
+    if (payload?.fn && http.request.path().startsWith('/rpc/')) {
+        const fn = decodeURIComponent(http.request.path().slice('/rpc/'.length));
+        if (fn && payload.fn !== fn) {
+            throw new UnauthorizedError();
+        }
+    }
+    if (payload?.session) {
+        try {
+            const decrypted = await decryptJSON(secret, payload.session);
+            if (decrypted?.session && setSession) {
+                await setSession(decrypted.session);
+            }
+        }
+        catch {
+            throw new UnauthorizedError();
+        }
+    }
+    return next();
+});

package/dist/middleware/timeout.d.ts

@@ -1,7 +1,7 @@
 export declare const timeout: () => import("../types/core.types.js").CorePikkuMiddlewareFactory<{
     timeout: number;
 }, import("../types/core.types.js").CoreSingletonServices<{
-    logLevel?: import("../index.js").LogLevel;
+    logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
-    workflow?: import("../index.js").WorkflowServiceConfig;
+    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

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

@@ -1,5 +1,5 @@
 import { pikkuState } from './pikku-state.js';
-import { freezeDedupe } from './utils.js';
+import { freezeDedupe, getTagGroups } from './utils.js';
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -75,7 +75,7 @@ export const addMiddleware = (tag, middleware, packageName = null) => {
  * This function looks up middleware that was registered with registerMiddleware.
  * It's used internally by the framework to resolve middleware references in metadata.
  *
- * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
+ * @param {string} name - The unique name (pikkuFuncId) of the middleware function.
  * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
  *
  * @internal
@@ -91,7 +91,9 @@ const middlewareCache = {
     channel: {},
     queue: {},
     scheduler: {},
+    trigger: {},
     mcp: {},
+    agent: {},
     cli: {},
     workflow: {},
 };
@@ -134,10 +136,8 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
                 }
             }
             else if (meta.type === 'tag') {
-                // Look up tag middleware group from pikkuState
-                const group = pikkuState(packageName, 'middleware', 'tagGroup')[meta.tag];
-                if (group) {
-                    // At runtime, all factories should be resolved to middleware
+                const groups = getTagGroups(pikkuState(packageName, 'middleware', 'tagGroup'), meta.tag);
+                for (const group of groups) {
                     resolved.push(...group);
                 }
             }
@@ -158,10 +158,8 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
     if (funcInheritedMiddleware) {
         for (const meta of funcInheritedMiddleware) {
             if (meta.type === 'tag') {
-                // Look up tag middleware group from pikkuState
-                const group = pikkuState(packageName, 'middleware', 'tagGroup')[meta.tag];
-                if (group) {
-                    // At runtime, all factories should be resolved to middleware
+                const groups = getTagGroups(pikkuState(packageName, 'middleware', 'tagGroup'), meta.tag);
+                for (const group of groups) {
                     resolved.push(...group);
                 }
             }

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

@@ -1,6 +1,6 @@
 import { pikkuState } from './pikku-state.js';
 import { ForbiddenError } from './errors/errors.js';
-import { freezeDedupe } from './utils.js';
+import { freezeDedupe, getTagGroups } from './utils.js';
 /**
  * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
  * @param services - The core services required for permission validation.
@@ -39,7 +39,7 @@ const verifyPermissions = async (permissions, services, data, wire) => {
  * This function looks up permissions that was registered with registerPermission.
  * It's used internally by the framework to resolve permission references in metadata.
  *
- * @param {string} name - The unique name (pikkuFuncName) of the permission function.
+ * @param {string} name - The unique name (pikkuFuncId) of the permission function.
  * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
  *
  * @internal
@@ -94,7 +94,9 @@ const combinedPermissionsCache = {
     channel: {},
     queue: {},
     scheduler: {},
+    trigger: {},
     mcp: {},
+    agent: {},
     cli: {},
     workflow: {},
 };
@@ -143,9 +145,8 @@ const combinePermissions = (wireType, uid, { wireInheritedPermissions, wirePermi
                 }
             }
             else if (meta.type === 'tag') {
-                // Look up tag permission group from pikkuState
-                const group = pikkuState(packageName, 'permissions', 'tagGroup')[meta.tag];
-                if (group) {
+                const groups = getTagGroups(pikkuState(packageName, 'permissions', 'tagGroup'), meta.tag);
+                for (const group of groups) {
                     if (Array.isArray(group)) {
                         resolved.push(...group);
                     }
@@ -176,9 +177,8 @@ const combinePermissions = (wireType, uid, { wireInheritedPermissions, wirePermi
     if (funcInheritedPermissions) {
         for (const meta of funcInheritedPermissions) {
             if (meta.type === 'tag') {
-                // Look up tag permission group from pikkuState
-                const group = pikkuState(packageName, 'permissions', 'tagGroup')[meta.tag];
-                if (group) {
+                const groups = getTagGroups(pikkuState(packageName, 'permissions', 'tagGroup'), meta.tag);
+                for (const group of groups) {
                     if (Array.isArray(group)) {
                         resolved.push(...group);
                     }
@@ -218,17 +218,13 @@ export const runPermissions = async (wireType, uid, { wireInheritedPermissions,
     });
     // Check all combined permissions - at least one must pass if any exist
     if (allPermissions.length > 0) {
-        let permissioned = false;
         for (const permission of allPermissions) {
             const result = await verifyPermissions(typeof permission === 'function' ? { permission } : permission, services, data, wire);
             if (result) {
-                permissioned = true;
-                // Continue executing all permissions (don't break early)
+                return;
             }
         }
-        if (!permissioned) {
-            services.logger.debug('Permission denied - combined permissions');
-            throw new ForbiddenError('Permission denied');
-        }
+        services.logger.debug('Permission denied - combined permissions');
+        throw new ForbiddenError('Permission denied');
     }
 };

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];
@@ -24,11 +23,14 @@ 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;

package/dist/pikku-state.js

@@ -1,7 +1,15 @@
+const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state');
+export const getAllPackageStates = () => {
+    if (!globalThis[PIKKU_STATE_KEY]) {
+        ;
+        globalThis[PIKKU_STATE_KEY] = new Map();
+    }
+    return globalThis[PIKKU_STATE_KEY];
+};
 /**
  * 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
@@ -11,17 +19,16 @@
  * // Main package
  * pikkuState(null, 'function', 'functions').get(funcName)
  *
- * // External package
+ * // Addon package
  * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
  */
 export const pikkuState = (packageName, type, content, value) => {
     const resolvedPackageName = packageName ?? '__main__';
     // Initialize package state if it doesn't exist
-    if (!globalThis.pikkuState ||
-        !globalThis.pikkuState.has(resolvedPackageName)) {
+    if (!getAllPackageStates().has(resolvedPackageName)) {
         initializePikkuState(resolvedPackageName);
     }
-    const packageState = globalThis.pikkuState.get(resolvedPackageName);
+    const packageState = getAllPackageStates().get(resolvedPackageName);
     if (value !== undefined) {
         packageState[type][content] = value;
     }
@@ -35,7 +42,7 @@ const createEmptyPackageState = () => ({
     rpc: {
         meta: {},
         files: new Map(),
-        externalPackages: new Map(),
+        addons: new Map(),
     },
     http: {
         middleware: new Map(),
@@ -65,23 +72,26 @@ const createEmptyPackageState = () => ({
     },
     workflows: {
         registrations: new Map(),
-        graphRegistrations: new Map(),
-        wirings: new Map(),
-        graphWirings: new Map(),
         meta: {},
     },
     trigger: {
+        functions: new Map(),
         triggers: new Map(),
+        triggerSources: new Map(),
         meta: {},
+        sourceMeta: {},
     },
     mcp: {
         resources: new Map(),
         resourcesMeta: {},
-        tools: new Map(),
         toolsMeta: {},
         prompts: new Map(),
         promptsMeta: {},
     },
+    agent: {
+        agents: new Map(),
+        agentsMeta: {},
+    },
     cli: {
         meta: { programs: {}, renderers: {} },
         programs: {},
@@ -89,56 +99,69 @@ const createEmptyPackageState = () => ({
     middleware: {
         tagGroup: {},
         httpGroup: {},
-        tagGroupMeta: {},
-        httpGroupMeta: {},
+    },
+    channelMiddleware: {
+        tagGroup: {},
     },
     permissions: {
         tagGroup: {},
         httpGroup: {},
-        tagGroupMeta: {},
-        httpGroupMeta: {},
     },
     misc: {
         errors: new Map(),
         schemas: new Map(),
         middleware: {},
+        channelMiddleware: {},
         permissions: {},
     },
+    models: {
+        config: null,
+    },
     package: {
         factories: null,
         singletonServices: null,
+        metaDir: null,
     },
 });
 /**
  * Initialize state for a new package
  */
 export const initializePikkuState = (packageName) => {
-    if (!globalThis.pikkuState) {
-        globalThis.pikkuState = new Map();
-    }
-    if (!globalThis.pikkuState.has(packageName)) {
-        globalThis.pikkuState.set(packageName, createEmptyPackageState());
+    if (!getAllPackageStates().has(packageName)) {
+        getAllPackageStates().set(packageName, createEmptyPackageState());
     }
 };
 export const resetPikkuState = () => {
     // Preserve the errors map before resetting
-    const existingErrors = globalThis.pikkuState?.get('__main__')?.misc.errors;
-    globalThis.pikkuState = new Map();
+    const existingErrors = getAllPackageStates().get('__main__')?.misc.errors;
+    globalThis[PIKKU_STATE_KEY] = new Map();
     initializePikkuState('__main__');
     // Restore the errors map if it existed
     if (existingErrors) {
-        const mainState = globalThis.pikkuState.get('__main__');
+        const mainState = getAllPackageStates().get('__main__');
         mainState.misc.errors = existingErrors;
     }
 };
-if (!globalThis.pikkuState) {
+if (!getAllPackageStates().has('__main__')) {
     resetPikkuState();
 }
+export const getPikkuMetaDir = (packageName) => {
+    return pikkuState(packageName ?? null, 'package', 'metaDir');
+};
+export const getSingletonServices = () => {
+    const services = pikkuState(null, 'package', 'singletonServices');
+    if (!services)
+        throw new Error('Singleton services not initialized');
+    return services;
+};
+export const getCreateWireServices = () => {
+    return pikkuState(null, 'package', 'factories')?.createWireServices;
+};
 /**
- * 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 const addPackageServiceFactories = (packageName, factories) => {

package/dist/schema.d.ts

@@ -1,17 +1,17 @@
-import { Logger } from './services/logger.js';
-import { SchemaService } from './services/schema-service.js';
+import type { Logger } from './services/logger.js';
+import type { SchemaService } from './services/schema-service.js';
 /**
  * Adds a schema to the schemas map for a specific package.
  * @param name - The name of the schema.
  * @param value - The schema value.
- * @param packageName - The package name (null for main package, '@scope/package' for external packages).
+ * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
  * @ignore
  */
 export declare const addSchema: (name: string, value: any, packageName?: string | null) => void;
 /**
  * Retrieves a schema from the schemas map for a specific package.
  * @param name - The name of the schema.
- * @param packageName - The package name (null for main package, '@scope/package' for external packages).
+ * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
  * @returns The schema value or undefined if not found.
  * @ignore
  */