@lowdefy/api 5.6.0 → 6.1.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/createEvaluateOperators.js

@@ -23,8 +23,10 @@ function createEvaluateOperators(context) {
         secrets,
         user
     });
-    function evaluateOperators({ input, items, location, payload, state, steps }) {
+    function evaluateOperators({ arrayIndices, error, input, items, location, payload, state, steps }) {
         const { output, errors } = operatorsParser.parse({
+            arrayIndices,
+            error,
             input,
             items,
             location,

package/dist/context/getCurrentEnvironment.js

@@ -0,0 +1,27 @@
+/*
+  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.
+*/ // The environment this deployment is, resolved by the build from LOWDEFY_ENVIRONMENT into
+// config.environment and config.environments. Null when no current environment is set or when it
+// is not declared, so callers fall back to their own defaults.
+function getCurrentEnvironment({ config }) {
+    const name = config?.environment;
+    const settings = config?.environments?.[name];
+    if (settings === undefined) return null;
+    return {
+        ...settings,
+        name
+    };
+}
+export default getCurrentEnvironment;

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

@@ -15,14 +15,25 @@
 */ 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 createWireProjection from './response/createWireProjection.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';
 import redactErrorResponse from './response/redactErrorResponse.js';
 import redactResponse from './response/redactResponse.js';
-export { buildEndpointResult, callAgent, callEndpoint, callRequest, createApiContext, createSessionCallback, getHomeAndMenus, getNextAuthConfig, getPageConfig, getRootConfig, logClientError, redactErrorResponse, redactResponse };
+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, createWireProjection, getAuthConfig, getAuthStrategies, getHomeAndMenus, getPageConfig, getRootConfig, logClientError, redactErrorResponse, redactResponse, resolveStrategyCaller, forwardScheduledEndpoint, runDetachedEndpoint, runWebhookEndpoint, runScheduledEndpoint };

package/dist/response/buildEndpointResult.js

@@ -17,7 +17,9 @@ 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.
+// it - see redactResponse for why the response needs the policy at all. `error` is
+// redactErrorResponse's error payload, so in dev it carries `devError`; `response`
+// never does.
 function buildEndpointResult(context, { error, response, status }) {
     const success = ![
         'error',

package/dist/response/createWireProjection.js

@@ -0,0 +1,88 @@
+/*
+  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 { lowdefyErrorNames, readErrorCodes } from '@lowdefy/errors';
+import { translate } from '@lowdefy/helpers';
+// The framework writes these messages to reveal nothing, and clients branch on
+// them, so they keep their text where every other non-author error does not.
+const AUTH_REFUSAL_NAMES = new Set([
+    'AuthenticationError',
+    'AuthorizationError',
+    'TwoFactorEnrolmentRequiredError'
+]);
+// The client-bound error policy, as an allowlist. Passed to serializer.serialize
+// as `projectError`, so it runs at every error node the walk emits - the cause
+// chain, an Error-valued own property, an Error nested in a response value - and
+// cannot become depth-limited.
+//
+// Only the author's message crosses. A library's message embeds whatever the
+// library saw - URLs with credentials, SQL, hostnames - so every other error
+// becomes one translated generic message plus the fields client config branches
+// on. The full error stays in the server log, and in dev reaches the developer
+// through `devError`, which config never reads.
+//
+// The context is optional: a websocket broadcast has no single request, so it
+// passes no `rid`, and the server error handler can run before any request
+// context exists.
+function createWireProjection(context) {
+    const requestId = context?.rid;
+    const genericMessage = translate({
+        key: 'server.genericError',
+        i18n: context?.i18n
+    });
+    return function project(err) {
+        // A PluginError defaults configKey to null; the walk only drops undefined.
+        const configKey = err.configKey ?? undefined;
+        // Keyed on the name rather than instanceof: the error may come from another
+        // copy of @lowdefy/errors or from a serializer round trip, where the class
+        // identity is gone but the name survives. The cause is returned raw so the
+        // walk projects it too - an Error cause takes the generic shape, and a
+        // non-Error cause is author data cleaned as a value.
+        if (err.name === 'UserError') {
+            return {
+                name: err.name,
+                message: err.message,
+                cause: err.cause,
+                metaData: err.metaData,
+                blockId: err.blockId,
+                pageId: err.pageId,
+                isReject: err.isReject,
+                configKey,
+                // Not read from the node: a caught error rebuilt for `_error` keeps only
+                // its class, and without the flag the client wraps a rethrown UserError
+                // in an ActionError and reports it back to the server a second time.
+                isLowdefyError: true,
+                handled: err.handled,
+                requestId
+            };
+        }
+        const { code, statusCode } = readErrorCodes(err);
+        return {
+            // A foreign class name can itself say which library or driver failed.
+            name: lowdefyErrorNames.has(err.name) ? err.name : 'Error',
+            message: AUTH_REFUSAL_NAMES.has(err.name) ? err.message : genericMessage,
+            code,
+            statusCode,
+            configKey,
+            requestId,
+            // The client revives errors without running a constructor, so this flag
+            // exists there only if the wire carries it. Without it the action runner
+            // wraps the error in a new ActionError without `handled`, POSTs it back to
+            // /api/client-error, and the server logs and reports it a second time.
+            isLowdefyError: true,
+            handled: err.handled
+        };
+    };
+}
+export default createWireProjection;

package/dist/response/normalizeErrorSources.js

@@ -16,13 +16,12 @@
 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.
+// rather than on a map of where errors can appear means every position is visited
+// without re-deriving where the walk puts errors.
 //
-// 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.
+// The check matters because the payload also carries author-written data - 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);
 }
@@ -43,17 +42,15 @@ function stripConfigDirectory(value, prefix) {
     }
     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.
+// Makes `source` in the dev-only `devError` config-relative, never an absolute
+// server path, so the dev tools show the path the developer knows. The wire error
+// carries no `source` at all. resolveConfigLocation makes it absolute whenever the
+// context carries a configDirectory, which server-dev does.
 //
 // 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;
+    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

package/dist/response/redactErrorResponse.js

@@ -13,18 +13,52 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { serializer, type } from '@lowdefy/helpers';
+import createWireProjection from './createWireProjection.js';
 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.
+// The one error payload every route and transport sends for a thrown error, at
+// any status. Owning the serialization as well as the policy leaves no bare
+// serializer.serialize(error) in response position for a caller to forget.
+//
+// `~e` is the wire error - identical in dev and prod, because it is what app
+// config reads. In dev the payload also carries `devError`, the error as the dev
+// terminal logs it, for the dev tools. It sits beside `~e` rather than inside it:
+// the serializer's reviver replaces any object holding `~e` with its error, so a
+// plain deserialize of the payload drops `devError` and config never sees it.
+//
+// `received` is left out of devError at every node: on the request path it is
+// the evaluated request properties, resolved _secret values included, and the
+// dev server can be reached over a LAN or tunnel. The terminal still logs it.
+function projectDevError(err) {
+    const props = {
+        message: err.message,
+        name: err.name,
+        stack: err.stack,
+        cause: err.cause,
+        ...err
+    };
+    delete props.received;
+    return props;
+}
 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
-    }));
+    const payload = serializer.serialize(error, {
+        projectError: createWireProjection(context)
+    });
+    // The server error handler has no request context when it fails before the
+    // context middleware runs, so there is no mode to read and no devError.
+    if (context?.mode === 'dev') {
+        const full = serializer.serialize(error, {
+            projectError: projectDevError
+        });
+        payload.devError = normalizeErrorSources(context, {
+            '~e': {
+                ...full['~e'],
+                requestId: context.rid
+            }
+        });
+    }
+    return payload;
 }
 export default redactErrorResponse;

package/dist/response/redactResponse.js

@@ -13,19 +13,19 @@
   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';
+import createWireProjection from './createWireProjection.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.
+// in a value, so a response holding one is an error-serialization site too - a
+// grep for serialize(error) cannot see those sites, 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.
+// Same wire projection as the error field, because it reaches the same audience.
+// No devError, in any mode: an Error in a response value is data the routine
+// returned, not a failure of this request.
 function redactResponse(context, response) {
-    return normalizeErrorSources(context, serializer.serialize(response, {
-        omitErrorProps
-    }));
+    return serializer.serialize(response, {
+        projectError: createWireProjection(context)
+    });
 }
 export default redactResponse;

package/dist/routes/agent/callAgent.js

@@ -12,17 +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 { type } from '@lowdefy/helpers';
-import buildEndpointResult from '../../response/buildEndpointResult.js';
-import createEvaluateOperators from '../../context/createEvaluateOperators.js';
-import authorizeAgent from './authorizeAgent.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;
@@ -32,12 +23,6 @@ async function callAgent(context, { agentId, pageId, messages, conversationId, u
         agentId,
         pageId
     });
-    const agentConfig = await getAgentConfig(context, {
-        agentId
-    });
-    authorizeAgent(context, {
-        agentConfig
-    });
     const agentContext = {
         conversationId: conversationId ?? undefined,
         pageId,
@@ -45,174 +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
-            });
-            return buildEndpointResult(context, {
-                error,
-                response,
-                status
-            });
-        },
-        getEndpointConfig: async ({ endpointId })=>{
-            return getEndpointConfig(context, {
-                endpointId
-            });
-        },
-        getAgentConfig: async ({ agentId })=>{
-            const subAgentConfig = await getAgentConfig(context, {
-                agentId
-            });
-            authorizeAgent(context, {
-                agentConfig: subAgentConfig
-            });
-            return subAgentConfig;
-        },
-        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,