@pikku/core 0.12.63 → 0.12.64

package/dist/wirings/http/http.types.d.ts

@@ -1,7 +1,7 @@
 import type { SerializeOptions } from 'cookie';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
-import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePermissionGroup, CorePikkuFunctionConfig } from '../../function/functions.types.js';
+import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePikkuFunctionConfig } from '../../function/functions.types.js';
 type ExtractHTTPWiringParams<S extends string> = S extends `${string}:${infer Param}/${infer Rest}` ? Param | ExtractHTTPWiringParams<`/${Rest}`> : S extends `${string}:${infer Param}` ? Param : never;
 export type AssertHTTPWiringParams<In, HTTPWiring extends string> = ExtractHTTPWiringParams<HTTPWiring> extends keyof In ? unknown : [
     'Error: HTTPWiring parameters',
@@ -75,7 +75,6 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     route: R;
     method: HTTPMethod;
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: true;
     middleware?: PikkuMiddleware[];
     sse?: undefined;
@@ -83,7 +82,6 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     route: R;
     method: HTTPMethod;
     func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    permissions?: undefined;
     auth?: false;
     middleware?: PikkuMiddleware[];
     sse?: undefined;
@@ -91,7 +89,6 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     route: R;
     method: 'get';
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: true;
     middleware?: PikkuMiddleware[];
     sse?: boolean;
@@ -99,7 +96,6 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     route: R;
     method: 'get';
     func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    permissions?: undefined;
     auth?: false;
     middleware?: PikkuMiddleware[];
     sse?: boolean;
@@ -107,7 +103,6 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     route: R;
     method: 'post';
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: true;
     middleware?: PikkuMiddleware[];
     query?: Array<keyof In>;
@@ -116,7 +111,6 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     route: R;
     method: 'post';
     func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    permissions?: undefined;
     auth?: false;
     middleware?: PikkuMiddleware[];
     query?: Array<keyof In>;
@@ -188,7 +182,6 @@ export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, an
     route: string;
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
     auth?: boolean;
-    permissions?: CorePermissionGroup<PikkuPermission>;
     middleware?: PikkuMiddleware[];
     sse?: boolean;
 };
@@ -200,7 +193,6 @@ export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<an
     tags?: string[];
     auth?: boolean;
     middleware?: PikkuMiddleware[];
-    permissions?: CorePermissionGroup<PikkuPermission>;
 };
 /**
  * Nested route map - allows hierarchical organization

package/dist/wirings/mcp/mcp-runner.js

@@ -134,8 +134,6 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcp
             data: () => request.params,
             inheritedMiddleware: meta?.middleware,
             wireMiddleware: mcp?.middleware,
-            inheritedPermissions: meta?.permissions,
-            wirePermissions: mcp?.permissions,
             tags: mcp?.tags,
             wire,
             sessionService: mcpSessionService,

package/dist/wirings/mcp/mcp.types.d.ts

@@ -1,5 +1,5 @@
-import type { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
 /**
  * Extract URI parameters from MCP resource URI template.
  * E.g., "user/{userId}/post/{postId}" => "userId" | "postId"
@@ -25,27 +25,25 @@ export type PikkuMCP<Tools extends string = any> = {
 /**
  * Represents metadata for MCP resources, including name, description, and documentation.
  */
-export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'middleware' | 'permissions'> & {
+export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
 }>;
 /**
  * Represents metadata for MCP tools, including name, description, and documentation.
  */
-export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
+export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
 }>;
 /**
  * Represents metadata for MCP prompts, including name, description, and arguments.
  */
-export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
+export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
@@ -55,7 +53,6 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
         required: boolean;
     }>;
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
 }>;
 /**
  * Represents an MCP resource with specific properties.
@@ -72,7 +69,6 @@ export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePi
     func: PikkuFunctionConfig;
     tags?: string[];
     middleware?: PikkuMiddleware[];
-    permissions?: CorePermissionGroup<PikkuPermission>;
 };
 /**
  * Represents an MCP tool with specific properties.
@@ -87,7 +83,6 @@ export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuF
     tags?: string[];
     streaming?: boolean;
     middleware?: PikkuMiddleware[];
-    permissions?: CorePermissionGroup<PikkuPermission>;
 };
 /**
  * Represents an MCP prompt with specific properties.
@@ -100,7 +95,6 @@ export type CoreMCPPrompt<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikk
     func: PikkuFunctionConfig;
     tags?: string[];
     middleware?: PikkuMiddleware[];
-    permissions?: CorePermissionGroup<PikkuPermission>;
 };
 export type JsonRpcRequest = {
     jsonrpc: string;

package/dist/wirings/oauth2/index.d.ts

@@ -1,4 +1 @@
-export { OAuth2Client } from './oauth2-client.js';
-export { createOAuth2Handler } from './oauth2-routes.js';
-export type { CreateOAuth2HandlerOptions } from './oauth2-routes.js';
 export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js';

package/dist/wirings/oauth2/index.js

@@ -1,2 +1 @@
-export { OAuth2Client } from './oauth2-client.js';
-export { createOAuth2Handler } from './oauth2-routes.js';
+export {};

package/dist/wirings/rpc/addon-runner.d.ts

@@ -0,0 +1,28 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+/**
+ * A single wired addon instance: a namespace (wireAddon `name`) plus the
+ * per-instance name-aliases that remap the logical names the addon reads to
+ * the actual project secret/variable/credential names.
+ */
+export type AddonInstance = {
+    namespace: string;
+    secretOverrides?: Record<string, string>;
+    variableOverrides?: Record<string, string>;
+    credentialOverrides?: Record<string, string>;
+};
+/**
+ * Get or create singleton services for an addon instance.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The addon package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @param addonInstance - The wired instance whose overrides shape the services
+ * @returns The instance's singleton services
+ */
+export declare const getOrCreatePackageSingletonServices: (packageName: string, parentServices: CoreSingletonServices, addonInstance?: AddonInstance) => Promise<CoreSingletonServices>;
+/**
+ * Build the addon instance descriptor (namespace + per-instance overrides) for
+ * a bare intra-addon call, using the namespace currently executing on the wire.
+ * Returns undefined unless that namespace maps to the resolved package.
+ */
+export declare const addonInstanceForNamespace: (namespace: string | undefined, expectedPackage: string) => AddonInstance | undefined;

package/dist/wirings/rpc/addon-runner.js

@@ -0,0 +1,173 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Wrap a SecretService so that the logical secret names an addon reads are
+ * remapped to the actual project secret names via the instance's overrides.
+ */
+const aliasSecretService = (secrets, overrides) => {
+    const map = (key) => overrides[key] ?? key;
+    return {
+        getSecret: (key) => secrets.getSecret(map(key)),
+        hasSecret: (key) => secrets.hasSecret(map(key)),
+        setSecret: (key, value) => secrets.setSecret(map(key), value),
+        deleteSecret: (key) => secrets.deleteSecret(map(key)),
+        getSecrets: async (keys) => {
+            const result = await secrets.getSecrets(keys.map(map));
+            const out = {};
+            for (const logical of keys) {
+                const real = map(logical);
+                if (real in result)
+                    out[logical] = result[real];
+            }
+            return out;
+        },
+    };
+};
+/**
+ * Wrap a VariablesService so that the logical variable names an addon reads
+ * are remapped to the actual project variable names via the instance's overrides.
+ */
+const aliasVariablesService = (variables, overrides) => {
+    const map = (name) => overrides[name] ?? name;
+    return {
+        get: (name) => variables.get(map(name)),
+        getVariables: (names) => {
+            const result = variables.getVariables(names.map(map));
+            const remap = (r) => {
+                const out = {};
+                for (const logical of names) {
+                    const real = map(logical);
+                    if (real in r)
+                        out[logical] = r[real];
+                }
+                return out;
+            };
+            return result instanceof Promise
+                ? result.then(remap)
+                : remap(result);
+        },
+        getAll: () => variables.getAll(),
+        set: (name, value) => variables.set(map(name), value),
+        has: (name) => variables.has(map(name)),
+        delete: (name) => variables.delete(map(name)),
+    };
+};
+/**
+ * Find the consumer-defined namespace (from wireAddon) for a given addon package.
+ * Returns null if the package isn't registered as an addon.
+ */
+const findAddonNamespaceForPackage = (packageName) => {
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons)
+        return null;
+    for (const [namespace, cfg] of addons.entries()) {
+        if (cfg?.package === packageName)
+            return namespace;
+    }
+    return null;
+};
+/**
+ * Wrap a workflow service so that bare workflow names passed from inside an
+ * addon function are auto-prefixed with the addon's consumer-facing namespace.
+ * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
+ * the workflow registered under the addon's package scope and throws
+ * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
+ * namespace, which couples the addon to its caller.
+ *
+ * Explicit `'ns:name'` and bare names that already exist in root meta are
+ * unaffected; only bare names that would otherwise miss resolution get
+ * prefixed.
+ */
+const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
+    return new Proxy(service, {
+        get(target, prop, receiver) {
+            if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+                const original = Reflect.get(target, prop, receiver);
+                return function (name, ...rest) {
+                    if (typeof name === 'string' && !name.includes(':')) {
+                        // Prefer the known instance namespace; fall back to the
+                        // package's sole namespace when invoked without an instance.
+                        const ns = namespace ?? findAddonNamespaceForPackage(packageName);
+                        if (ns) {
+                            name = `${ns}:${name}`;
+                        }
+                    }
+                    return original.call(this, name, ...rest);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+};
+/**
+ * Get or create singleton services for an addon instance.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The addon package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @param addonInstance - The wired instance whose overrides shape the services
+ * @returns The instance's singleton services
+ */
+export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
+    // Cache per instance (namespace), not per package, so two instances of one
+    // package get separate services built with their own overrides. A bare
+    // package-scoped call (no instance) falls back to per-package caching.
+    const cacheKey = addonInstance?.namespace ?? packageName;
+    const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices');
+    if (cachedServices) {
+        return cachedServices;
+    }
+    const factories = pikkuState(packageName, 'package', 'factories');
+    if (!factories || !factories.createSingletonServices) {
+        // No factories registered, use parent services
+        return parentServices;
+    }
+    // Apply this instance's secret/variable overrides by aliasing the resolver
+    // services the addon reads from, so its createSingletonServices resolves
+    // instance-specific secrets/variables.
+    let existingServices = parentServices;
+    if (addonInstance?.secretOverrides && parentServices.secrets) {
+        existingServices = {
+            ...existingServices,
+            secrets: aliasSecretService(parentServices.secrets, addonInstance.secretOverrides),
+        };
+    }
+    if (addonInstance?.variableOverrides && parentServices.variables) {
+        existingServices = {
+            ...existingServices,
+            variables: aliasVariablesService(parentServices.variables, addonInstance.variableOverrides),
+        };
+    }
+    // Create config for the package (use parent config if no factory)
+    let config = existingServices.config;
+    if (factories.createConfig) {
+        config = await factories.createConfig(existingServices.variables);
+    }
+    // Create singleton services for the package, passing parent services as existing
+    const packageServices = await factories.createSingletonServices(config, existingServices);
+    // Wrap workflowService so that bare names used inside the addon's functions
+    // resolve to workflows registered under the addon's package scope.
+    if (packageServices.workflowService &&
+        typeof packageServices.workflowService === 'object') {
+        packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName, addonInstance?.namespace ?? null);
+    }
+    pikkuState(cacheKey, 'package', 'singletonServices', packageServices);
+    return packageServices;
+};
+/**
+ * Build the addon instance descriptor (namespace + per-instance overrides) for
+ * a bare intra-addon call, using the namespace currently executing on the wire.
+ * Returns undefined unless that namespace maps to the resolved package.
+ */
+export const addonInstanceForNamespace = (namespace, expectedPackage) => {
+    if (!namespace)
+        return undefined;
+    const cfg = pikkuState(null, 'addons', 'packages').get(namespace);
+    if (!cfg || cfg.package !== expectedPackage)
+        return undefined;
+    return {
+        namespace,
+        secretOverrides: cfg.secretOverrides,
+        variableOverrides: cfg.variableOverrides,
+        credentialOverrides: cfg.credentialOverrides,
+    };
+};

package/dist/wirings/rpc/index.d.ts

@@ -1,4 +1,8 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
+export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
+export type { RemoteAddonAuthBinding } from './remote-addon-auth.js';
 export type { PikkuRPC, RPCMeta } from './rpc-types.js';
 export { wireAddon } from './wire-addon.js';
 export type { WireAddonConfig } from './wire-addon.js';
+export { wireRemoteAddon } from './wire-remote-addon.js';
+export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';

package/dist/wirings/rpc/index.js

@@ -1,2 +1,4 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
+export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
 export { wireAddon } from './wire-addon.js';
+export { wireRemoteAddon } from './wire-remote-addon.js';

package/dist/wirings/rpc/remote-addon-auth.d.ts

@@ -0,0 +1,26 @@
+import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
+import { PikkuError } from '../../errors/error-handler.js';
+/**
+ * How a `wireRemoteAddon` consumer supplies the token the hosted addon expects.
+ * This is a CLIENT authenticating to a hosted library — not the trusted mesh.
+ */
+export type RemoteAddonAuthBinding = {
+    credentialId: string;
+} | {
+    secretId: string;
+} | {
+    resolve: (services: CoreServices, wire: PikkuRawWire) => string | Promise<string>;
+};
+/** The addon's auth was bound but the source produced no token — fail closed. */
+export declare class RemoteAddonAuthError extends PikkuError {
+    readonly namespace: string;
+    constructor(namespace: string, detail: string);
+}
+/**
+ * Resolve the bearer token for a remote addon call from the consumer's bound
+ * source. Returns `null` only when no auth is bound (a public surface).
+ *
+ * Security: the resolved token is never logged or traced; per-user credentials
+ * are read via the wire (scoped to `pikkuUserId`); an empty result fails closed.
+ */
+export declare function resolveRemoteAddonToken(auth: RemoteAddonAuthBinding | undefined, services: CoreServices, wire: PikkuRawWire, namespace: string): Promise<string | null>;

package/dist/wirings/rpc/remote-addon-auth.js

@@ -0,0 +1,43 @@
+import { PikkuError, addError } from '../../errors/error-handler.js';
+/** The addon's auth was bound but the source produced no token — fail closed. */
+export class RemoteAddonAuthError extends PikkuError {
+    namespace;
+    constructor(namespace, detail) {
+        super(`Remote addon '${namespace}' auth could not be resolved: ${detail}`);
+        this.namespace = namespace;
+    }
+}
+addError(RemoteAddonAuthError, {
+    status: 401,
+    message: 'Remote addon authentication could not be resolved.',
+});
+/**
+ * Resolve the bearer token for a remote addon call from the consumer's bound
+ * source. Returns `null` only when no auth is bound (a public surface).
+ *
+ * Security: the resolved token is never logged or traced; per-user credentials
+ * are read via the wire (scoped to `pikkuUserId`); an empty result fails closed.
+ */
+export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
+    if (!auth) {
+        // No auth bound → the addon declares its remote surface public.
+        return null;
+    }
+    let token;
+    if ('credentialId' in auth) {
+        if (typeof wire.getCredential !== 'function') {
+            throw new RemoteAddonAuthError(namespace, `credentialId '${auth.credentialId}' requires a wire with credential access`);
+        }
+        token = await wire.getCredential(auth.credentialId);
+    }
+    else if ('secretId' in auth) {
+        token = await services.secrets.getSecret(auth.secretId);
+    }
+    else if (typeof auth.resolve === 'function') {
+        token = await auth.resolve(services, wire);
+    }
+    if (token === null || token === undefined || token === '') {
+        throw new RemoteAddonAuthError(namespace, 'resolved token was empty');
+    }
+    return String(token);
+}

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -7,6 +7,15 @@ export declare class RPCNotFoundError extends PikkuError {
     readonly rpcName: string;
     constructor(rpcName: string);
 }
+/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
+export declare class RemoteAddonConfigError extends PikkuError {
+    constructor(namespace: string, detail: string);
+}
+/** The hosted addon returned a non-2xx response for a remote RPC. */
+export declare class RemoteAddonRequestError extends PikkuError {
+    readonly httpStatus: number;
+    constructor(namespace: string, fnName: string, status: number, detail: string);
+}
 import type { AIAgentInput } from '../ai-agent/ai-agent.types.js';
 import type { StreamAIAgentOptions } from '../ai-agent/ai-agent-prepare.js';
 /**
@@ -32,6 +41,15 @@ export declare class ContextAwareRPCService {
      * @private
      */
     private invokeAddonFunction;
+    /**
+     * Dispatch a `wireRemoteAddon` RPC over HTTP to the hosting service.
+     *
+     * The consumer sends the addon's own function name (not the namespaced form)
+     * to the host's `/remote/rpc/:rpcName` endpoint, authenticating as a client
+     * with the token bound in `wireRemoteAddon({ auth })`. The addon's handlers
+     * live on the host, so there is no local function meta to resolve.
+     */
+    private invokeRemoteAddonFunction;
     rpcWithWire<In = any, Out = any>(rpcName: string, data: In, wire: PikkuRawWire): Promise<Out>;
     startWorkflow<In = any>(workflowName: string, input: In, options?: {
         startNode?: string;
@@ -103,5 +121,6 @@ export declare const rpcService: PikkuRPCService<import("../../types/core.types.
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>, PikkuRPC>;