@lowdefy/api 5.5.1 → 6.0.0

package/dist/context/createAuthorize.js

@@ -13,7 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { ConfigError } from '@lowdefy/errors';
-function createAuthorize({ session }) {
+function createAuthorize({ session, system = false }) {
     // Next-auth getSession provides a session object if the user is authenticated
     // else session will be null
     const authenticated = !!session;
@@ -24,6 +24,9 @@ function createAuthorize({ session }) {
         });
     }
     function authorize(config) {
+        // A system context (scheduled, webhook, detached runs) was authorized at the
+        // transport layer, so nested endpoint calls are never gated on a user session.
+        if (system === true) return true;
         const { auth } = config;
         if (auth.public === true) return true;
         if (auth.public === false) {

package/dist/context/resolveStrategyCaller.js

@@ -0,0 +1,56 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+// Tries the configured API auth strategies in config order; the first
+// verifier match wins. A strategy caller is a config-derived, org-less
+// principal: roles are the strategy's static grant unioned with any
+// claim-derived roles, and attributes are the static bag shallow-merged
+// with claim-mapped values (claim wins), so _user.attributes reads the same
+// for session and strategy callers.
+async function resolveStrategyCaller({ headers, logger, strategies }) {
+    for (const strategy of strategies ?? []){
+        const match = await strategy.verify({
+            headers,
+            logger
+        });
+        if (type.isNone(match)) {
+            continue;
+        }
+        const roles = [
+            ...new Set([
+                ...strategy.roles,
+                ...match.roles ?? []
+            ])
+        ];
+        const attributes = {
+            ...strategy.attributes,
+            ...match.attributes ?? {}
+        };
+        logger.debug({
+            event: 'auth_strategy_authenticated',
+            authMethod: strategy.type,
+            strategyId: strategy.id
+        }, `Request authenticated by auth strategy "${strategy.id}" (${strategy.type}).`);
+        return {
+            ...match.user,
+            authMethod: strategy.type,
+            strategyId: strategy.id,
+            roles,
+            attributes
+        };
+    }
+    return null;
+}
+export default resolveStrategyCaller;

package/dist/index.js

@@ -12,14 +12,27 @@
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-*/ import callAgent from './routes/agent/callAgent.js';
+*/ import buildEndpointResult from './response/buildEndpointResult.js';
+import callAgent from './routes/agent/callAgent.js';
 import callEndpoint from './routes/endpoints/callEndpoint.js';
+import getEndpointConfig from './routes/endpoints/getEndpointConfig.js';
 import callRequest from './routes/request/callRequest.js';
 import createApiContext from './context/createApiContext.js';
+import createChannelRegistry from './routes/websocket/createChannelRegistry.js';
+import createMcpServer from './routes/mcp/createMcpServer.js';
+import createWebSocketConnection from './routes/websocket/createWebSocketConnection.js';
 import createSessionCallback from './routes/auth/callbacks/createSessionCallback.js';
+import getAuthConfig from './routes/auth/getAuthConfig.js';
+import getAuthStrategies from './routes/auth/strategies/getAuthStrategies.js';
 import getHomeAndMenus from './routes/rootConfig/getHomeAndMenus.js';
-import getNextAuthConfig from './routes/auth/getNextAuthConfig.js';
+import resolveStrategyCaller from './context/resolveStrategyCaller.js';
 import getPageConfig from './routes/page/getPageConfig.js';
 import getRootConfig from './routes/rootConfig/getRootConfig.js';
 import logClientError from './routes/log/logClientError.js';
-export { callAgent, callEndpoint, callRequest, createApiContext, createSessionCallback, getHomeAndMenus, getNextAuthConfig, getPageConfig, getRootConfig, logClientError };
+import redactErrorResponse from './response/redactErrorResponse.js';
+import redactResponse from './response/redactResponse.js';
+import forwardScheduledEndpoint from './routes/endpoints/forwardScheduledEndpoint.js';
+import runDetachedEndpoint from './routes/endpoints/runDetachedEndpoint.js';
+import runWebhookEndpoint from './routes/endpoints/runWebhookEndpoint.js';
+import runScheduledEndpoint from './routes/endpoints/runScheduledEndpoint.js';
+export { buildEndpointResult, callAgent, callEndpoint, getEndpointConfig, callRequest, createApiContext, createChannelRegistry, createMcpServer, createSessionCallback, createWebSocketConnection, getAuthConfig, getAuthStrategies, getHomeAndMenus, getPageConfig, getRootConfig, logClientError, redactErrorResponse, redactResponse, resolveStrategyCaller, forwardScheduledEndpoint, runDetachedEndpoint, runWebhookEndpoint, runScheduledEndpoint };

package/dist/response/buildEndpointResult.js

@@ -0,0 +1,33 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import redactErrorResponse from './redactErrorResponse.js';
+import redactResponse from './redactResponse.js';
+// The wire object every endpoint route returns after running its routine. One
+// function rather than a copy of the same return statement per route, so the
+// `response` field cannot end up policed differently from the `error` field beside
+// it - see redactResponse for why the response needs the policy at all.
+function buildEndpointResult(context, { error, response, status }) {
+    const success = ![
+        'error',
+        'reject'
+    ].includes(status);
+    return {
+        error: redactErrorResponse(context, error),
+        response: redactResponse(context, response),
+        status: success ? 'success' : status,
+        success
+    };
+}
+export default buildEndpointResult;

package/dist/response/normalizeErrorSources.js

@@ -0,0 +1,64 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import path from 'path';
+import { type } from '@lowdefy/helpers';
+// extractErrorProps emits a nested error as a plain props object, not as a second
+// '~e' wrapper, so an error node is recognised by its shape. Keying on the shape
+// rather than on a map of where errors can appear is deliberate: re-deriving those
+// positions is the mistake the walk-level omit exists to avoid, and this predicate
+// still visits every position.
+//
+// The check matters because the payload also carries author-written data the policy
+// deliberately preserves - a UserError's non-Error cause, its metaData - and a
+// `source` key inside those belongs to the app, not to us.
+function isErrorNode(value) {
+    return type.isString(value.name) && type.isString(value.message);
+}
+// A prefix slice rather than path.relative or a parse of a `path:line` shape:
+// source is `${resolvedPath}:${lineNumber}` only when a line number resolved and
+// the bare path otherwise, and removing a prefix never touches the suffix, so both
+// forms work without knowing which this is. Applied at every error node carrying a
+// source, not only the outermost, because a strip is a no-op when the prefix is
+// absent. Mutates the freshly serialized payload in place - nothing else holds it.
+function stripConfigDirectory(value, prefix) {
+    if (type.isArray(value)) {
+        value.forEach((item)=>stripConfigDirectory(item, prefix));
+        return;
+    }
+    if (!type.isObject(value)) return;
+    if (isErrorNode(value) && type.isString(value.source) && value.source.startsWith(prefix)) {
+        value.source = value.source.slice(prefix.length);
+    }
+    Object.values(value).forEach((child)=>stripConfigDirectory(child, prefix));
+}
+// Guarantees `source` reaches a client config-relative, never as an absolute server
+// path. resolveConfigLocation makes it absolute whenever the context carries a
+// configDirectory - server-dev and server-e2e do, and production happens not to
+// today by omission rather than by invariant, which is the drift this closes.
+//
+// A rewrite rather than an omission, and it needs the context, so it runs as a pass
+// over the serialized payload instead of inside the walk.
+function normalizeErrorSources(context, payload) {
+    // errorHandler has an else branch for requests with no lowdefyContext, so a
+    // missing context is a supported call - it only means no source to normalise.
+    const configDirectory = context?.configDirectory;
+    if (type.isNone(configDirectory)) return payload;
+    // configDirectory is `LOWDEFY_DIRECTORY_CONFIG || process.cwd()` at every site
+    // that sets it, so it may be relative or carry a trailing separator, while
+    // resolveConfigLocation built source with path.resolve. Compare normalised.
+    stripConfigDirectory(payload, `${path.resolve(configDirectory)}${path.sep}`);
+    return payload;
+}
+export default normalizeErrorSources;

package/dist/response/omitErrorProps.js

@@ -0,0 +1,51 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { UserError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+// The client-bound error policy: which fields of an error may cross the wire.
+// Passed to serializer.serialize as `omitErrorProps`, so extractErrorProps applies
+// it at EVERY error node the walk emits - the cause chain, an Error-valued own
+// property, and an Error nested inside a plain object or array. The policy is
+// stated against the emitter rather than against a response shape, so it cannot
+// become depth-limited.
+//
+// `received` is not merely "may be sensitive": on the request path
+// callRequestResolver sets it to the EVALUATED request properties, so a _secret
+// resolved into a request header is in it. `stack` exposes server internals,
+// including absolute node_modules paths. Both are unbounded runtime data nobody
+// chose, in every environment - the full value stays in the server log, which is
+// where a developer on their own machine reads it.
+const ALWAYS_OMITTED = [
+    'received',
+    'stack'
+];
+const OMITTED_WITH_CAUSE = [
+    ...ALWAYS_OMITTED,
+    'cause'
+];
+function omitErrorProps(error) {
+    // An Error cause is the trace the browser renders (name + message per level),
+    // so it is always kept - fields are taken from causes, causes are never pruned.
+    // A non-Error cause is internal server config: the whole endpoint routine, a
+    // control node, ajv errors. UserError is the exception, the one class whose
+    // payload the author wrote for the client.
+    //
+    // type.isError is `instanceof Error`, the same test extractErrorProps uses to
+    // decide which branch emits the cause - the two must agree.
+    if (type.isError(error.cause)) return ALWAYS_OMITTED;
+    if (error instanceof UserError) return ALWAYS_OMITTED;
+    return OMITTED_WITH_CAUSE;
+}
+export default omitErrorProps;

package/dist/response/redactErrorResponse.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { serializer, type } from '@lowdefy/helpers';
+import normalizeErrorSources from './normalizeErrorSources.js';
+import omitErrorProps from './omitErrorProps.js';
+// Owns the serialization as well as the policy, so the policy cannot be forgotten:
+// no bare serializer.serialize(error) is left in response position to wrap. Every
+// route returning an error to a caller - any status, any transport - goes through
+// here or through buildEndpointResult.
+function redactErrorResponse(context, error) {
+    // Endpoint routes serialize the error field on success too, where it is null.
+    // Passing that through unchanged keeps them from emitting an empty {'~e'}.
+    if (type.isNone(error)) return error;
+    return normalizeErrorSources(context, serializer.serialize(error, {
+        omitErrorProps
+    }));
+}
+export default redactErrorResponse;

package/dist/response/redactResponse.js

@@ -0,0 +1,31 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { serializer } from '@lowdefy/helpers';
+import normalizeErrorSources from './normalizeErrorSources.js';
+import omitErrorProps from './omitErrorProps.js';
+// The response-value call shape, beside redactErrorResponse's error-only one.
+// A response is not an error, but makeReplacer wraps any Error it meets anywhere
+// in a value, so a response holding one is an error-serialization site too - the
+// grep that enumerated those sites could not see them, which is why this exists
+// as a function rather than as a rule to remember.
+//
+// Same policy as the error field, because it reaches the same audience: a browser
+// for a request or endpoint body, a third party for cron and detached.
+function redactResponse(context, response) {
+    return normalizeErrorSources(context, serializer.serialize(response, {
+        omitErrorProps
+    }));
+}
+export default redactResponse;

package/dist/routes/agent/authorizeAgent.js

@@ -0,0 +1,39 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigError } from '@lowdefy/errors';
+import { translate } from '@lowdefy/helpers';
+function authorizeAgent({ authorize, i18n, logger }, { agentConfig }) {
+    if (!authorize(agentConfig)) {
+        logger.debug({
+            event: 'debug_agent_authorize',
+            authorized: false,
+            auth_config: agentConfig.auth
+        });
+        // Same message as an unknown agentId so responses do not reveal which agents exist.
+        throw new ConfigError(translate({
+            key: 'agent.runtime.agentNotFound',
+            values: {
+                agentId: agentConfig.agentId
+            },
+            i18n
+        }));
+    }
+    logger.debug({
+        event: 'debug_agent_authorize',
+        authorized: true,
+        auth_config: agentConfig.auth
+    });
+}
+export default authorizeAgent;

package/dist/routes/agent/callAgent.js

@@ -12,15 +12,8 @@
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-*/ import { serializer, type } from '@lowdefy/helpers';
-import createEvaluateOperators from '../../context/createEvaluateOperators.js';
-import authorizeApiEndpoint from '../endpoints/authorizeApiEndpoint.js';
-import getEndpointConfig from '../endpoints/getEndpointConfig.js';
-import runRoutine from '../endpoints/runRoutine.js';
-import getAgentConfig from './getAgentConfig.js';
-import getAgentResolver from './getAgentResolver.js';
-import getConnectionConfig from '../connections/getConnectionConfig.js';
-import getConnection from '../connections/getConnection.js';
+*/ import createEvaluateOperators from '../../context/createEvaluateOperators.js';
+import prepareAgent from './prepareAgent.js';
 async function callAgent(context, { agentId, pageId, messages, conversationId, urlQuery, sharedState }) {
     const { logger } = context;
     context.pageId = pageId;
@@ -30,9 +23,6 @@ async function callAgent(context, { agentId, pageId, messages, conversationId, u
         agentId,
         pageId
     });
-    const agentConfig = await getAgentConfig(context, {
-        agentId
-    });
     const agentContext = {
         conversationId: conversationId ?? undefined,
         pageId,
@@ -40,175 +30,12 @@ async function callAgent(context, { agentId, pageId, messages, conversationId, u
         urlQuery: urlQuery ?? {},
         userId: context.user?.sub ?? context.user?.id ?? null
     };
-    // Evaluate operators in agent properties (e.g. _user, _secret, _payload)
-    agentConfig.properties = context.evaluateOperators({
-        input: agentConfig.properties ?? {},
-        location: agentConfig.agentId,
-        payload: agentContext,
-        state: {},
-        steps: {}
-    });
-    // Load connection config from build artifacts using agent's connectionId
-    const connectionConfig = await getConnectionConfig(context, {
-        connectionId: agentConfig.connectionId,
-        configKey: agentConfig['~k']
-    });
-    // Get connection plugin from registry
-    const connection = getConnection(context, {
-        connectionConfig
-    });
-    // Evaluate operators in connection properties
-    const connectionProperties = context.evaluateOperators({
-        input: connectionConfig.properties || {},
-        location: connectionConfig.connectionId,
-        payload: {},
-        state: {},
-        steps: {}
-    });
-    // Create connection instance (e.g., Anthropic provider)
-    const connectionInstance = connection.create({
-        connection: connectionProperties
-    });
-    // Get agent type from plugin registry
-    const agentType = getAgentResolver(context, {
-        agentConfig
-    });
-    // Build resolver context with callEndpoint that allows InternalApi endpoints
-    const resolverContext = {
+    const { agentConfig, connectionInstance, agentType, resolverContext } = await prepareAgent(context, {
+        agentId,
         agentContext,
-        i18n: context.i18n,
-        evaluateOperators: (input)=>context.evaluateOperators({
-                input,
-                location: agentConfig.agentId,
-                payload: agentContext,
-                state: {},
-                steps: {}
-            }),
-        callEndpoint: async (endpointId, { payload, abortSignal })=>{
-            const endpointConfig = await getEndpointConfig(context, {
-                endpointId
-            });
-            authorizeApiEndpoint(context, {
-                endpointConfig
-            });
-            const routineContext = {
-                steps: {},
-                payload: payload ?? {},
-                arrayIndices: [],
-                items: {},
-                state: {},
-                endpointDepth: 0
-            };
-            const { error, response, status } = await runRoutine(context, routineContext, {
-                routine: endpointConfig.routine
-            });
-            const success = ![
-                'error',
-                'reject'
-            ].includes(status);
-            return {
-                error: serializer.serialize(error),
-                response: serializer.serialize(response),
-                status: success ? 'success' : status,
-                success
-            };
-        },
-        getEndpointConfig: async ({ endpointId })=>{
-            return getEndpointConfig(context, {
-                endpointId
-            });
-        },
-        getAgentConfig: async ({ agentId })=>{
-            return getAgentConfig(context, {
-                agentId
-            });
-        },
-        getConnectionForAgent: async ({ agentConfig: subAgentConfig })=>{
-            const subConnectionConfig = await getConnectionConfig(context, {
-                connectionId: subAgentConfig.connectionId,
-                configKey: subAgentConfig['~k']
-            });
-            const subConnection = getConnection(context, {
-                connectionConfig: subConnectionConfig
-            });
-            const subConnectionProperties = context.evaluateOperators({
-                input: subConnectionConfig.properties || {},
-                location: subConnectionConfig.connectionId,
-                payload: {},
-                state: {},
-                steps: {}
-            });
-            return subConnection.create({
-                connection: subConnectionProperties
-            });
-        },
-        resolveMcpSources: async ({ agentConfig: subAgentConfig })=>{
-            const resolvedMcp = [];
-            for (const mcpSource of subAgentConfig.mcp ?? []){
-                if (!type.isNone(mcpSource.connectionId)) {
-                    const mcpConnConfig = await getConnectionConfig(context, {
-                        connectionId: mcpSource.connectionId,
-                        configKey: subAgentConfig['~k']
-                    });
-                    const mcpConnection = getConnection(context, {
-                        connectionConfig: mcpConnConfig
-                    });
-                    const mcpConnProps = context.evaluateOperators({
-                        input: mcpConnConfig.properties || {},
-                        location: mcpConnConfig.connectionId,
-                        payload: {},
-                        state: {},
-                        steps: {}
-                    });
-                    const mcpConfig = mcpConnection.create({
-                        connection: mcpConnProps
-                    });
-                    const { connectionId: _, ...overrides } = mcpSource;
-                    resolvedMcp.push({
-                        ...mcpConfig,
-                        ...overrides
-                    });
-                } else {
-                    resolvedMcp.push(mcpSource);
-                }
-            }
-            return resolvedMcp;
-        }
-    };
-    // Resolve MCP connection references to inline config.
-    // Agent-level overrides (like confirm) may still contain operators —
-    // handleAgentChat evaluates those via its existing evaluateOperators call.
-    const resolvedMcp = [];
-    for (const mcpSource of agentConfig.mcp ?? []){
-        if (!type.isNone(mcpSource.connectionId)) {
-            const mcpConnConfig = await getConnectionConfig(context, {
-                connectionId: mcpSource.connectionId,
-                configKey: agentConfig['~k']
-            });
-            const mcpConnection = getConnection(context, {
-                connectionConfig: mcpConnConfig
-            });
-            const mcpConnProps = context.evaluateOperators({
-                input: mcpConnConfig.properties || {},
-                location: mcpConnConfig.connectionId,
-                payload: {},
-                state: {},
-                steps: {}
-            });
-            const mcpConfig = mcpConnection.create({
-                connection: mcpConnProps
-            });
-            // Merge: connection properties as base, agent-level overrides on top
-            const { connectionId: _, ...overrides } = mcpSource;
-            resolvedMcp.push({
-                ...mcpConfig,
-                ...overrides
-            });
-        } else {
-            resolvedMcp.push(mcpSource);
-        }
-    }
-    agentConfig.mcp = resolvedMcp;
+        endpointDepth: 0,
+        mode: 'chat'
+    });
     // Call the agent resolver
     const { response } = await agentType.resolver({
         connection: connectionInstance,