@lowdefy/api 0.0.0-experimental-20260827092002 → 0.0.0-experimental-20260827092153

package/dist/context/applySystemTrust.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 createAuthorizeOutcome from './createAuthorizeOutcome.js';
+// The single writer of the trusted, caller-less system-context invariants
+// (Decision 1). It sets all three together on an existing context so no caller
+// can set one without the others:
+//   - user: null      — caller-less (detectable via type.isNone)
+//   - system: true     — the run-level trust marker every authorization layer reads
+//   - authorizeOutcome — derived from createAuthorizeOutcome so it reads context.system
+// createSystemContext builds a FRESH context for the off-request hook path;
+// this applies the same state to a request context a runner already holds
+// (cron at construction, webhook once its verify gate passes, a detached run
+// whose dispatcher was itself a system context). One greppable place means a
+// future runner cannot reintroduce the silent-no-op bug by forgetting a line.
+function applySystemTrust(context) {
+    context.user = null;
+    context.system = true;
+    context.authorizeOutcome = createAuthorizeOutcome(context);
+    return context;
+}
+export default applySystemTrust;

package/dist/context/createApiContext.js

@@ -12,11 +12,14 @@
   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 createAuthorize from './createAuthorize.js';
+*/ import createAuthorizeOutcome from './createAuthorizeOutcome.js';
 import createReadConfigFile from './createReadConfigFile.js';
+import getAuthEnforcement from '../routes/auth/getAuthEnforcement.js';
+import getOrganizationBinding from '../routes/auth/organizations/getOrganizationBinding.js';
 import resolveLocale from './resolveLocale.js';
 function createApiContext(context) {
-    context.user = context?.session?.user;
+    // context.user is written by resolveAuthentication (or a pre-resolved
+    // dev/e2e caller) before this runs - never assigned here.
     if (context.i18n?.defaultLocale) {
         const active = resolveLocale({
             i18n: context.i18n,
@@ -29,7 +32,19 @@ function createApiContext(context) {
     } else {
         context.i18n = undefined;
     }
-    context.authorize = createAuthorize(context);
+    // The retained organizations state ({ policy, pinned }) - read by the
+    // _organization operator and the org-scoped admin steps; null when auth
+    // (or organizations) is not configured.
+    context.organization = getOrganizationBinding({
+        auth: context.auth ?? null
+    });
+    // The retained build-time authorization facts - the enrolment floor, the exempt
+    // enrolment page, and the unlisted-page-id default. null when auth is not
+    // configured, in which case nothing is protected and nothing is required.
+    context.authEnforcement = getAuthEnforcement({
+        auth: context.auth ?? null
+    });
+    context.authorizeOutcome = createAuthorizeOutcome(context);
     context.readConfigFile = createReadConfigFile(context);
 }
 export default createApiContext;

package/dist/context/createAuthorizeOutcome.js

@@ -0,0 +1,91 @@
+/*
+  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';
+import { ConfigError } from '@lowdefy/errors';
+// createAuthorizeOutcome is called with the context object on every path
+// (createApiContext, applySystemTrust, and the runners), so `system` is read
+// straight off context.system - the single run-level trust marker every
+// authorization layer reads.
+//
+// It returns an OUTCOME, not a boolean: 'allow', 'deny', or 'enrol_required'.
+// The rename is load-bearing. Every previous caller was a truthiness test, and
+// every non-empty string is truthy, so a caller left on `authorize` would read
+// 'deny' as authorized and stop enforcing auth entirely on that surface. There
+// is deliberately NO boolean authorize left beside this - a missed call site
+// must throw TypeError, which also catches callers outside this repo.
+//
+// The ordering is security-critical and written here exactly once. Enrolment is
+// checked LAST, after roles: checking it first hands an unenrolled caller an
+// enrol redirect for every protected page that EXISTS and /404 for those that do
+// not, which is a working page-enumeration oracle over pages they have no access
+// to. Checked last, they see the enrol outcome only for pages they would have
+// been let into - which tells them exactly what an enrolled caller learns by
+// getting the page.
+function createAuthorizeOutcome({ authEnforcement, system, user }) {
+    const authenticated = !type.isNone(user);
+    // A caller awaiting an organization is signed in and holds no membership -
+    // under tenant, the invited user before they accept (resolveAuthentication).
+    // They are known so the always-public accept page can address them, and
+    // refused everywhere auth.public is false, roles or not: empty roles is not a
+    // wall (user-model Decision 2), so authenticated alone must not admit them to
+    // a role-less protected page. Strategy callers (apiKey, jwt) also hold no
+    // organization but sit deliberately outside the membership boundary, so the
+    // test is this explicit marker, never the absence of an organization. The
+    // caller is the normalizeCaller-snaked record, so the key is snake_case here.
+    const awaitingOrganization = user?.awaiting_organization === true;
+    const roles = user?.roles ?? [];
+    if (!Array.isArray(roles) || roles.some((role)=>!type.isString(role))) {
+        throw new ConfigError('user.roles must be an array of strings.', {
+            received: roles
+        });
+    }
+    const enrolmentRequired = authEnforcement?.twoFactorRequired === true;
+    const enrolPageId = authEnforcement?.twoFactorEnrolPageId ?? null;
+    // pageId is passed only by the page route. Requests, endpoints, websockets and
+    // menu items pass none, so the enrolment-page exemption cannot be reached by a
+    // request id that happens to collide with the enrol page's id.
+    function authorizeOutcome(config, { pageId } = {}) {
+        // A system context has no session and no caller, so "does this caller's
+        // session carry the required roles?" is undefined, not denied - and it holds
+        // no factor either, so the enrolment floor is undefined for it too.
+        if (system === true) return 'allow';
+        const { auth } = config;
+        if (auth.public === true) return 'allow';
+        if (auth.public === false) {
+            if (!authenticated) return 'deny';
+            if (awaitingOrganization) return 'deny';
+            if (auth.roles && !auth.roles.some((role)=>roles.includes(role))) return 'deny';
+            // Enrolment last, after roles. Strictly === false: the key is present only
+            // on a caller resolved from a session, so API strategy callers and the
+            // dev/e2e injected callers pass untouched by inheritance rather than by a
+            // carve-out (Decision 10). `!user.two_factor_enrolled` would redirect every
+            // one of them.
+            if (enrolmentRequired && user.two_factor_enrolled === false) {
+                // The enrolment page itself is exempt from the enrolment check alone -
+                // it is a protected page and stays one; this is not a public-ness
+                // exemption (Decision 8).
+                if (!type.isNone(pageId) && pageId === enrolPageId) return 'allow';
+                return 'enrol_required';
+            }
+            return 'allow';
+        }
+        throw new ConfigError('auth.public must be true or false.', {
+            received: auth.public,
+            configKey: config['~k']
+        });
+    }
+    return authorizeOutcome;
+}
+export default createAuthorizeOutcome;

package/dist/context/createEvaluateOperators.js

@@ -14,12 +14,13 @@
   limitations under the License.
 */ import { ServerParser } from '@lowdefy/operators';
 function createEvaluateOperators(context) {
-    const { appMeta, i18n, jsMap, operators, secrets, user } = context;
+    const { appMeta, i18n, jsMap, operators, organization, secrets, user } = context;
     const operatorsParser = new ServerParser({
         i18n,
         jsMap,
         lowdefyApp: appMeta,
         operators,
+        organization,
         secrets,
         user
     });

package/dist/context/createSystemContext.js

@@ -0,0 +1,78 @@
+/*
+  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 applySystemTrust from './applySystemTrust.js';
+import createEvaluateOperators from './createEvaluateOperators.js';
+import createReadConfigFile from './createReadConfigFile.js';
+import getAuthEnforcement from '../routes/auth/getAuthEnforcement.js';
+import getOrganizationBinding from '../routes/auth/organizations/getOrganizationBinding.js';
+// Builds a fresh off-request context for a trusted, caller-less system context -
+// an auth hook fire. The caller is the auth engine, not a user: `user` is null
+// so the run is detectable as caller-less (`type.isNone(context.user)`) and
+// `_user` resolves to nothing (the hook's subject is in `_payload`). The run is
+// trusted at construction (`context.system = true`), the single trust marker
+// every authorization layer reads (Decision 1); its `authorizeOutcome` is derived
+// from createAuthorizeOutcome like every other layer, so endpoint auth is not
+// re-checked against a session (Decision 2).
+function createSystemContext({ agents, appMeta, auth, buildDirectory, config, configDirectory, connections, createHandleError, fileCache, i18n, jsMap, logger, notifications, operators, rid, secrets, steps, websockets }) {
+    const context = {
+        rid,
+        agents,
+        appMeta,
+        auth,
+        buildDirectory,
+        config,
+        configDirectory,
+        connections,
+        fileCache,
+        headers: {},
+        i18n: i18n?.defaultLocale ? {
+            ...i18n,
+            active: i18n.defaultLocale
+        } : undefined,
+        jsMap,
+        logger,
+        notifications,
+        operators,
+        req: {
+            url: 'system:auth-hook',
+            method: null,
+            hostname: null
+        },
+        secrets,
+        steps,
+        websockets
+    };
+    // Hook routines read the retained organizations state too - a step or
+    // _organization inside a hook-bound endpoint resolves the same pinned org.
+    context.organization = getOrganizationBinding({
+        auth: auth ?? null
+    });
+    // A system context bypasses the enrolment check outright (system === true
+    // returns early), so this exists for shape consistency, not a live read.
+    context.authEnforcement = getAuthEnforcement({
+        auth: auth ?? null
+    });
+    // Trusted, caller-less system context (Decisions 1, 2): user: null,
+    // system: true, and authorizeOutcome derived from createAuthorizeOutcome - the
+    // same invariant bundle the caller-less runners apply, set in one place.
+    applySystemTrust(context);
+    context.handleError = createHandleError({
+        context
+    });
+    context.readConfigFile = createReadConfigFile(context);
+    context.evaluateOperators = createEvaluateOperators(context);
+    return context;
+}
+export default createSystemContext;

package/dist/context/normalizeInjectedCaller.js

@@ -0,0 +1,50 @@
+/*
+  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 { normalizeCaller, type } from '@lowdefy/helpers';
+// The single writer of the pre-resolved-caller shape. A dev mock user, the dev
+// headless renderer cookie, and the e2e test cookie each substitute for the
+// whole resolveAuthentication step, and must match the shape it produces -
+// including its snake_case keys, so an injected caller may be authored either
+// way and still reads like a resolved one. That output always carries roles as
+// an array and attributes as an object (a whole-bag { _user: 'attributes' }
+// read gives {} on a real caller), so both are floored here. profile,
+// contact_id, active_organization_id and two_factor_enrolled are only ever
+// produced by a real user-row/member read, so they are left exactly as the
+// caller carries them - absent stays absent, and a bare _user.profile read is
+// null-safe.
+// organization_id (the tenant wall's org value) mirrors resolveAuthentication,
+// where it always equals active_organization_id - an injected caller declaring
+// either key gets both, so mock/e2e callers pass walled connections without
+// duplicating the org under two names. A caller with neither stays org-less
+// and fails closed on walled connections, same as a strategy caller.
+//
+// The floors read the raw user: roles, attributes and profile are single words
+// that snake to themselves, so an authored key and its normalized name are the
+// same key. The org floor reads the normalized object, where either authored
+// spelling has already collapsed onto one name.
+function normalizeInjectedCaller(user) {
+    const normalized = {
+        ...normalizeCaller(user),
+        roles: user.roles ?? [],
+        attributes: user.attributes ?? {}
+    };
+    const organizationId = normalized.organization_id ?? normalized.active_organization_id;
+    if (!type.isNone(organizationId)) {
+        normalized.organization_id = organizationId;
+        normalized.active_organization_id = normalized.active_organization_id ?? organizationId;
+    }
+    return normalized;
+}
+export default normalizeInjectedCaller;