@lowdefy/api 5.5.1 → 5.6.0

package/dist/index.js

@@ -12,7 +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 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 callRequest from './routes/request/callRequest.js';
 import createApiContext from './context/createApiContext.js';
@@ -22,4 +23,6 @@ import getNextAuthConfig from './routes/auth/getNextAuthConfig.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';
+export { buildEndpointResult, callAgent, callEndpoint, callRequest, createApiContext, createSessionCallback, getHomeAndMenus, getNextAuthConfig, getPageConfig, getRootConfig, logClientError, redactErrorResponse, redactResponse };

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,8 +12,10 @@
   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 { 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';
@@ -33,6 +35,9 @@ async function callAgent(context, { agentId, pageId, messages, conversationId, u
     const agentConfig = await getAgentConfig(context, {
         agentId
     });
+    authorizeAgent(context, {
+        agentConfig
+    });
     const agentContext = {
         conversationId: conversationId ?? undefined,
         pageId,
@@ -102,16 +107,11 @@ async function callAgent(context, { agentId, pageId, messages, conversationId, u
             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
-            };
+            return buildEndpointResult(context, {
+                error,
+                response,
+                status
+            });
         },
         getEndpointConfig: async ({ endpointId })=>{
             return getEndpointConfig(context, {
@@ -119,9 +119,13 @@ async function callAgent(context, { agentId, pageId, messages, conversationId, u
             });
         },
         getAgentConfig: async ({ agentId })=>{
-            return getAgentConfig(context, {
+            const subAgentConfig = await getAgentConfig(context, {
                 agentId
             });
+            authorizeAgent(context, {
+                agentConfig: subAgentConfig
+            });
+            return subAgentConfig;
         },
         getConnectionForAgent: async ({ agentConfig: subAgentConfig })=>{
             const subConnectionConfig = await getConnectionConfig(context, {

package/dist/routes/endpoints/addStepResult.js

@@ -12,12 +12,22 @@
   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 { set } from '@lowdefy/helpers';
+*/ import { ConfigError } from '@lowdefy/errors';
+import { ReservedKeyError, set } from '@lowdefy/helpers';
 function addStepResult(context, routineContext, { result, stepId }) {
     const key = [
         stepId,
         ...routineContext.arrayIndices
     ].join('.');
-    set(routineContext.steps, key, result);
+    try {
+        set(routineContext.steps, key, result);
+    } catch (error) {
+        if (error instanceof ReservedKeyError) {
+            throw new ConfigError(`Reserved step id "${error.segment}" cannot be used`, {
+                cause: error
+            });
+        }
+        throw error;
+    }
 }
 export default addStepResult;

package/dist/routes/endpoints/callEndpoint.js

@@ -15,6 +15,7 @@
 */ import { serializer } from '@lowdefy/helpers';
 import { ConfigError } from '@lowdefy/errors';
 import authorizeApiEndpoint from './authorizeApiEndpoint.js';
+import buildEndpointResult from '../../response/buildEndpointResult.js';
 import createEvaluateOperators from '../../context/createEvaluateOperators.js';
 import getEndpointConfig from './getEndpointConfig.js';
 import runRoutine from './runRoutine.js';
@@ -59,15 +60,10 @@ async function callEndpoint(context, { blockId, endpointId, pageId, payload }) {
     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
-    };
+    return buildEndpointResult(context, {
+        error,
+        response,
+        status
+    });
 }
 export default callEndpoint;

package/dist/routes/endpoints/control/controlSetState.js

@@ -12,7 +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 { set } from '@lowdefy/helpers';
+*/ import { ConfigError } from '@lowdefy/errors';
+import { ReservedKeyError, set } from '@lowdefy/helpers';
 function controlSetState(context, routineContext, { control }) {
     const { logger, evaluateOperators } = context;
     const { items } = routineContext;
@@ -30,7 +31,17 @@ function controlSetState(context, routineContext, { control }) {
         evaluated: evaluatedSetState
     });
     Object.entries(evaluatedSetState).forEach(([key, value])=>{
-        set(routineContext.state, key, value);
+        try {
+            set(routineContext.state, key, value);
+        } catch (error) {
+            if (error instanceof ReservedKeyError) {
+                throw new ConfigError(`Reserved key "${error.segment}" cannot be used in :set_state`, {
+                    cause: error,
+                    configKey: control['~k']
+                });
+            }
+            throw error;
+        }
     });
     return {
         status: 'continue'

package/dist/routes/endpoints/runRoutine.js

@@ -68,9 +68,11 @@ async function runRoutine(context, routineContext, { routine }) {
                 error
             };
         }
+        // handleError sets error.handled once it has logged - it is the single sink
+        // that owns the flag, so a nested runRoutine re-throwing this error does not
+        // log it again.
         if (!error.handled) {
             await context.handleError(error);
-            error.handled = true;
         }
         return {
             status: 'error',

package/dist/routes/request/callRequest.js

@@ -24,6 +24,7 @@ import getRequestConfig from './getRequestConfig.js';
 import getRequestResolver from './getRequestResolver.js';
 import validateSchemas from './validateSchemas.js';
 import createEvaluateOperators from '../../context/createEvaluateOperators.js';
+import redactResponse from '../../response/redactResponse.js';
 async function callRequest(context, { blockId, pageId, payload, requestId }) {
     const { logger } = context;
     context.blockId = blockId;
@@ -93,7 +94,7 @@ async function callRequest(context, { blockId, pageId, payload, requestId }) {
         id: requestConfig.id,
         success: true,
         type: requestConfig.type,
-        response: serializer.serialize(response)
+        response: redactResponse(context, response)
     };
 }
 export default callRequest;

package/dist/test/testContext.js

@@ -13,7 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import createAuthorize from '../context/createAuthorize.js';
-function testContext({ appMeta = {}, config = {}, connections = {}, headers = {}, logger = {
+function testContext({ appMeta = {}, config = {}, configDirectory, connections = {}, headers = {}, logger = {
     debug: ()=>{},
     error: ()=>{},
     info: ()=>{},
@@ -27,9 +27,14 @@ function testContext({ appMeta = {}, config = {}, connections = {}, headers = {}
             session
         }),
         config,
+        configDirectory,
         connections,
+        // Mirrors the servers' createHandleError contract: the sink logs the error
+        // and marks it handled, which is what runRoutine's guard and the client's
+        // already-logged check both read.
         handleError: async (error)=>{
             logger.error(error);
+            error.handled = true;
         },
         headers,
         logger,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/api",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -34,13 +34,13 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/ajv": "5.5.1",
-    "@lowdefy/errors": "5.5.1",
-    "@lowdefy/helpers": "5.5.1",
-    "@lowdefy/node-utils": "5.5.1",
-    "@lowdefy/nunjucks": "5.5.1",
-    "@lowdefy/operators": "5.5.1",
-    "@lowdefy/operators-js": "5.5.1"
+    "@lowdefy/ajv": "5.6.0",
+    "@lowdefy/errors": "5.6.0",
+    "@lowdefy/helpers": "5.6.0",
+    "@lowdefy/node-utils": "5.6.0",
+    "@lowdefy/nunjucks": "5.6.0",
+    "@lowdefy/operators": "5.6.0",
+    "@lowdefy/operators-js": "5.6.0"
   },
   "devDependencies": {
     "@jest/globals": "28.1.3",