@wildo-ai/saas-backend-lib 1.1.0 → 1.1.2

package/dist/esm/security/authorizations/services/authorizations.backend.service.js

@@ -11,13 +11,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { inject, injectable, optional } from "inversify";
-import { anyOrganizationUnitGrantInheritsDownward, CORE_APP_ROLES, expandOrganizationUnitGrantThroughInheritance, isOrganizationWideRoleInfo, OrganizationUnitNarrowingDecisionKind, resolveOrganizationUnitNarrowingDecision, isWildoBackendError, } from "@wildo-ai/saas-models";
+import { anyOrganizationUnitGrantInheritsDownward, CORE_APP_ROLES, expandOrganizationUnitGrantThroughInheritance, isOrganizationWideRoleInfo, OrganizationUnitNarrowingDecisionKind, requiredRolesDeclarePublicAccess, resolveOrganizationUnitNarrowingDecision, isWildoBackendError, } from "@wildo-ai/saas-models";
 import { SAAS_SERVICE_TYPES } from "../../../inject/models/service-types.js";
 import { LoggerService } from "../../../monitoring/logger/services/logger.service.js";
 import { ErrorBuilderBackendService } from "../../../errors/services/error-builder.backend.service.js";
 import { describeCaughtError, projectCaughtErrorLogFields } from "../../../errors/utils/error-log-level-classification.backend.utils.js";
 import { RepositoriesRegistryHandlerBackendService } from "../../../base-classes/services/repositories/repositories-registry-handler.backend.service.js";
-import { CoreResourceType, coreResourceShared_FieldIdentifier, PlatformAccessGrantStatus, PlatformAccessGrants_Operations, ResourcePrimaryScope, isPlatformAccessGrantUsable, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, ErrorType, ErrorCustomMessageReference, DEFAULT_APP_ROLE_CONFIGURATION, DEFAULT_ORGANIZATION_ROLES, CoreResourceOperation, ExecutionContext_ExecutionType, ResourceOperationDenialReason, ResourceOperationRiskLevel } from "@wildo-ai/saas-models";
+import { CoreResourceType, IntrospectionTenancyStance, PersistenceAdapter, coreResourceShared_FieldIdentifier, PlatformAccessGrantStatus, PlatformAccessGrants_Operations, ResourcePrimaryScope, isPlatformAccessGrantUsable, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, ErrorType, ErrorCustomMessageReference, DEFAULT_APP_ROLE_CONFIGURATION, DEFAULT_ORGANIZATION_ROLES, CoreResourceOperation, ResourceOperationDenialReason, ResourceOperationRiskLevel } from "@wildo-ai/saas-models";
 import { classifyAuthorizationDenial, resolveDenialAuditEmissionDecision } from "../../../security/authorizations/authorization-denial-audit.backend.utils.js";
 import { isOwnScopeRootResource } from "../../../security/authorizations/scope-root-collection-confinement.backend.js";
 let AuthorizationsBackendService = class AuthorizationsBackendService {
@@ -352,10 +352,16 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      *
      * Read from the OPERATION rather than inferred from the context, so the public carve-out above
      * cannot be satisfied by the caller's side of the request alone.
+     *
+     * Delegates to {@link requiredRolesDeclarePublicAccess}, the ONE named source for what
+     * `APP_PUBLIC` means. This used to be a private re-derivation of the same two-line test, and it
+     * was one of FOUR such copies (this one, the authentication tier's `operationAdmitsPublicAccess`,
+     * and the two role gates that did not have one and therefore refused credentialed callers). A
+     * policy expressed as a module-private constant reaches exactly the sites that already agree with
+     * it — see `.claude/rules/invariant-call-site-enumeration.md` #13.
      */
     operationDeclaresPublicAccess(operation) {
-        const roles = operation.roles;
-        return Array.isArray(roles) && roles.includes(CORE_APP_ROLES.APP_PUBLIC);
+        return requiredRolesDeclarePublicAccess(operation.roles);
     }
     async authorizeInRepositoryAndService(id_or_ids, operation, executionContext) {
         const { resourceIdentifier, operationIdentifier, variantType, resourcePrimaryScope, roles: operationRoles } = operation;
@@ -391,11 +397,22 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
          * does not declare `APP_PUBLIC` cannot reach here, because `ExecutionContextCreator` only mints a
          * public context for an operation that does.
          *
-         * BOTH conditions are required on purpose. Keying on the context alone would let any future
-         * public-context path reach a non-public operation; keying on the operation alone would admit a
+         * BOTH conditions are required on purpose, and the reason has NARROWED since this was written.
+         * Keying on the context alone would let any future public-context path reach a non-public
+         * operation — that half is unchanged and is the security-relevant one.
+         *
+         * The other half used to be argued as "keying on the operation alone would admit a
          * credentialed-but-unauthorized caller to a public operation's addressed form without their roles
-         * being examined. Together they say exactly one thing: nobody claimed an identity, and none was
-         * required.
+         * being examined". That framing is retired (#153): a credentialed caller IS now admitted to a
+         * publicly-declared operation — `validateOperationRoles` treats `APP_PUBLIC` as imposing no
+         * positive role requirement, because a declaration that reduced access for presenting a valid
+         * credential was the defect, not the design.
+         *
+         * What the `isPublicExecution()` half still buys is that the credentialed caller takes the FULL
+         * path rather than this shortcut: their row pre-fetch runs, their FK-path and parent-scope gates
+         * run, and their roles are examined and found to require nothing. This carve-out remains what it
+         * says — nobody claimed an identity, and none was required — and is not the mechanism by which an
+         * authenticated caller reaches a public operation.
          */
         if (executionContext.isPublicExecution() && this.operationDeclaresPublicAccess(operation)) {
             this.logDebug('Public execution of a publicly-declared operation — no principal to authorize; '
@@ -544,7 +561,49 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
             resourceObjects = (idsArray.length === 1) ? [obj_s] : obj_s;
         }
         catch (error) {
-            const authError = this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+            /**
+             * "No rows" and "could not look" are DIFFERENT ANSWERS, and this catch used to
+             * destroy the difference.
+             *
+             * It classified every failure of the authorization pre-fetch as `NOT_FOUND`, so an
+             * infrastructure fault reached the client as a missing row. Measured on the dogfood
+             * stack 2026-09-01: **78 of 78** recent 404s carried
+             * `authorizations_validation_failed`, and NOT ONE of them was an absent record —
+             * every one was `introspection_derivation_failed`, the introspection repository
+             * refusing because the target application had not been built. That producer takes
+             * explicit care to distinguish the two ("This is reported rather than returned as an
+             * empty result, because 'no rows' and 'could not look' are different answers") and
+             * the distinction died here, four frames later.
+             *
+             * The cost is not cosmetic. It sends every reader to the database for a fault that is
+             * in the build; it reports a SERVER fault as a CLIENT error, so a 4xx/5xx alert split
+             * cannot see it; and it makes a broken deployment indistinguishable from an empty one.
+             *
+             * ## Why re-classifying here is safe for the existence oracle
+             *
+             * The anti-enumeration refusals are ELSEWHERE and are untouched: a row that is absent
+             * OR invisible is caught by the `resourceObjects.length !== idsArray.length` check
+             * below, which answers `NOT_FOUND` with this same message reference on purpose.
+             * Genuine absence never reaches THIS catch — it arrives as a successful read returning
+             * fewer rows, not as a throw.
+             *
+             * So this block only ever sees a fetch that FAILED, and a failure that is independent
+             * of the id (a broken build, a dead connection, a missing operation key) reveals
+             * nothing about any particular row. A cause that IS `NOT_FOUND` still answers
+             * `NOT_FOUND`, unchanged, so the repository's own filtered-out refusal keeps its
+             * indistinguishability.
+             *
+             * The `customMessageReference` is deliberately the SAME in every branch: the sibling
+             * refusal at `buildSubjectNotResolvableError` notes that a different reference would
+             * restore the oracle one field lower down, and that reasoning binds here too.
+             */
+            const causeErrorType = isWildoBackendError(error) ? error.type : undefined;
+            const fetchFailureErrorType = causeErrorType === undefined
+                // Not one of ours — a driver error, a TypeError. A server fault by definition, and
+                // the one case where the old behavior was least defensible.
+                ? ErrorType.INTERNAL
+                : causeErrorType;
+            const authError = this.errorBuilder.buildError(fetchFailureErrorType, executionContext, {
                 customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_VALIDATION_FAILED,
                 context: {
                     message: `Failed to fetch resource objects for authorization: ${describeCaughtError(error)}`,
@@ -1074,10 +1133,65 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
             }
         }
     }
+    /**
+     * Does this resource DERIVE tenant-anchorless rows rather than store rows under the application?
+     *
+     * An INTROSPECTION resource declaring {@link IntrospectionTenancyStance.APPLICATION_STRUCTURE} or
+     * {@link IntrospectionTenancyStance.APPLICATION_RUNTIME} has no per-row application anchor, and
+     * that is its contract rather than an omission: its rows are DERIVED per read (from a companion
+     * behavior over the application's source, or from the companion's own runtime services), there is
+     * no store to hold a foreign key, and both stances say outright that there is no tenant dimension
+     * for a scope predicate to filter on. What separates the two stances is the READ POSTURE
+     * (structure may be `APP_PUBLIC`; runtime must be role-gated), which is the operation variants'
+     * job and ran before this method — not the anchor question answered here.
+     *
+     * Fails CLOSED in both directions that matter. With no registry bound the answer is `false`, so
+     * the anchor check below still runs; and the stance must be one of the two enumerated anchorless
+     * members, so an introspection resource that projects anything else — including a future scoped
+     * stance — keeps the check.
+     */
+    projectsAnchorlessIntrospection(resourceIdentifier) {
+        const configuration = this.resourcesRegistry?.tryGetResourceConfiguration(resourceIdentifier);
+        const tenancy = configuration?.introspectionBinding?.tenancy;
+        return configuration?.persistenceAdapter === PersistenceAdapter.INTROSPECTION
+            && (tenancy === IntrospectionTenancyStance.APPLICATION_STRUCTURE
+                || tenancy === IntrospectionTenancyStance.APPLICATION_RUNTIME);
+    }
     /**
      * Authorize APPLICATION scope
+     *
+     * ## What the per-row anchor check does, and what it cannot do
+     *
+     * The application is a SINGLETON per database — `ExecutionContextCreator.getApplicationId()` reads
+     * the APPLICATION row with an empty filter, on the stated grounds that "there is one APPLICATION
+     * row, so nothing can usefully narrow this read". So `appIdFromResource !== applicationId` cannot
+     * discriminate between applications within a database: both sides resolve to the same row. It is a
+     * consistency assertion about correctly-populated rows, not a cross-application isolation control.
+     *
+     * The `!appIdFromResource` branch is the one with teeth, and for a STORED resource it is right —
+     * every `APPLICATION`-anchored resource in the engine declares
+     * `parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION]`, so its
+     * rows carry the FK and a row without one is malformed.
+     *
+     * A projection cannot satisfy it at all, which is why the stance is consulted first. Measured
+     * before the carve-out existed: an addressed READ on `workbenchApplicationModules` answered 200 to
+     * an anonymous caller (the public-execution path returns before this method) and 403 to an
+     * authenticated one, while LIST answered 200 to both (collection operations run no row check). The
+     * resource could not be fixed from the application side without inventing a field its schema does
+     * not declare.
      */
     async authorizeApplication(resourceObject, resourceIdentifier, initiatorIds, executionContext) {
+        /*
+         * Read as: this resource's rows ARE the application, so there is no row-level membership left to
+         * check. Deliberately NOT an opt-out flag an operation can declare — a stored resource that
+         * simply forgot its FK must keep failing, and only a declared tenancy stance can tell the two
+         * apart. Nothing else is relaxed: the operation's `roles` gate ran before this, and the
+         * repository's contextual filter runs underneath.
+         */
+        if (this.projectsAnchorlessIntrospection(resourceIdentifier)) {
+            this.logDebug('Anchorless introspection projection — no per-row anchor to authorize', { resourceIdentifier });
+            return;
+        }
         if (resourceIdentifier === CoreResourceType.APPLICATION) {
             // For application resources, check that the resource _id matches the initiator applicationId
             if (resourceObject._id !== initiatorIds.applicationId) {
@@ -1130,6 +1244,29 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      */
     narrowableResourceIdentifier) {
         const { initiatorRoles } = executionContext;
+        /*
+         * A PUBLICLY-DECLARED operation imposes no positive role requirement — on ANY caller.
+         *
+         * This is the ROLE half of `APP_PUBLIC`, and it is separate from the public-EXECUTION carve-out
+         * at the top of `authorizeInRepositoryAndService`. That one answers "there is no principal to
+         * authorize"; this one answers "there is a principal, and the operation asks nothing of them".
+         * Both are needed, and having only the first is what produced the defect this closes: an
+         * anonymous probe was admitted by the carve-out while the SAME request carrying a valid token
+         * fell through to here and was refused, because `APP_PUBLIC` is in nobody's granted role set.
+         *
+         * Placed BEFORE the org-wide grant computation deliberately. A public declaration is a statement
+         * about the OPERATION, so it cannot depend on which grants the caller happens to hold, on the
+         * scope those grants resolve against, or on whether a unit-narrowing stamp exists — every one of
+         * which is an input the computation below reads and none of which can change the answer.
+         *
+         * It relaxes the ROLE question only. `validateParentScopeAccess`, `validateFKRelationshipAccess`
+         * and the repository's contextual filter all still run, so a public declaration never widens
+         * WHICH ROWS a caller reaches — only whether they may ask.
+         */
+        if (requiredRolesDeclarePublicAccess(operationRoles)) {
+            this.logDebug('Operation declares APP_PUBLIC — no positive role requirement for any caller', { operationRoles });
+            return;
+        }
         // ORGANIZATION-WIDE GRANTS ONLY in this computation. A unit-scoped entry (`organizationUnitId`
         // present) confers authority inside ONE organization unit, so it must not satisfy an operation
         // gate that asks an organization-wide question — otherwise "ORG_MANAGER of Sales" would pass every
@@ -1313,6 +1450,32 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      * - id_or_ids must be a valid string or array
      * - Authorization additionally verifies access to the specific resource(s)
      */
+    /**
+     * Authorize an operation on ROLES ALONE, with no row to fetch.
+     *
+     * ## Why this exists, and why it is deliberately narrow
+     *
+     * Every other entry point here authorizes an operation against ROWS — it pre-fetches them, checks
+     * scope, checks FK reachability, then checks roles. That is right whenever there is a row.
+     *
+     * A WebSocket SCOPE subscription has none. It says "tell me when anything of this type changes
+     * under this scope", which addresses no instance, so the row-shaped questions have no subject and
+     * only the role question remains. Passing a scope id in the row's place is the trap this avoids:
+     * it would authorize a READ of a row of the subscribed type whose id happens to be an application
+     * id, which is not a question anyone asked and which fails for the wrong reason.
+     *
+     * **This is strictly WEAKER than `authorizeInController` and must never be substituted for it on a
+     * path that has an id.** It answers "may this principal invoke this operation at all", not "may
+     * this principal reach this row". Its only caller is the scope-subscription gate, where the
+     * notification it admits carries row identities the caller could have listed anyway.
+     *
+     * Unit narrowing still applies: `resourceIdentifier` is forwarded, so a unit-scoped grant can
+     * rescue a failing role check exactly as it does everywhere else.
+     */
+    async authorizeOperationRolesOnly(operation, executionContext) {
+        const { roles: operationRoles, resourceIdentifier } = operation;
+        await this.validateOperationRoles(operationRoles, executionContext, resourceIdentifier);
+    }
     async authorizeInController(id_or_ids, executionContext) {
         // Extract operation from execution context
         const operation = executionContext.operation;
@@ -1498,11 +1661,24 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      * This prevents users from accessing resources assigned to or created by other users
      * by manipulating the URL path.
      *
-     * Authorization behavior by execution type:
-     * - USER_REQUEST: Must match the authenticated user's ID
-     * - API_KEY: Allowed - API keys have broader access within their scope
-     * - INTERNAL: Allowed - internal operations bypass FK validation
-     * - PUBLIC: Allowed - public operations don't have identity context
+     * The gate is on IDENTITY, not on execution type (issue #321). A context is admitted on a user-FK
+     * path when it carries a `userId` AND that id equals the one in the path — whatever established the
+     * identity. Two execution types carry a `userId`:
+     * - USER_REQUEST — the session's own user;
+     * - CONSUMABLE_TOKEN — the `userId` the token was MINTED for (`createExecutionContextFromRequest`
+     *   copies `consumableTokenObject.userId` onto `initiatorIds`). It is server-minted, so a bearer can
+     *   only act as that subject on that path — the same trust a session confers.
+     * Machine principals, INTERNAL, PUBLIC, WEBHOOK and ANONYMOUS_SESSION never reach the gate: the
+     * early return below skips FK matching for them entirely (machine principals have broader access
+     * within their scope; the others carry no person to match). So the identity gate is evaluated for
+     * exactly two execution types — USER_REQUEST and CONSUMABLE_TOKEN — and a context of either kind
+     * WITHOUT a `userId` is refused: a user-FK path names a person, and a caller with no person cannot
+     * be that person.
+     *
+     * History: after the early return, this used to refuse every non-USER_REQUEST type — which, given
+     * that return, meant exactly CONSUMABLE_TOKEN — on the stated premise that "only USER_REQUEST has a
+     * userId". The premise was false when written (the token bridge already set it); the effect was
+     * that no token could act on a user-FK path even for the very user it was minted for.
      */
     async validateFKRelationshipAccess(executionContext) {
         const { relationshipContexts, initiatorIds, executionType } = executionContext;
@@ -1538,21 +1714,9 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
             }
             // Validate based on the target resource type
             if (resourceType === CoreResourceType.USERS || resourceType === CoreResourceType.USER_SELF) {
-                // User FK paths require the authenticated user to match the URL userId
-                // Only USER_REQUEST type has userId in initiatorIds
-                if (executionType !== ExecutionContext_ExecutionType.USER_REQUEST) {
-                    // Consumable tokens cannot access user FK paths
-                    throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
-                        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
-                        context: {
-                            // diagnostic (log-only)
-                            relationshipField,
-                            resourceIdInUrl: resourceId,
-                            executionType
-                        }
-                    });
-                }
-                // User must be authenticated
+                // A user-FK path names a person. Admission requires a `userId` on the context (USER_REQUEST
+                // session or CONSUMABLE_TOKEN minted for that user) that EQUALS the one in the path. There is
+                // deliberately no execution-type branch here — see the method JSDoc (issue #321).
                 if (!initiatorIds?.userId) {
                     throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
                         customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
@@ -1805,9 +1969,25 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      * Validate that user's roles satisfy the required operation roles
      * Considers role hierarchy within the given scope
      *
-     * @returns true if user has at least one of the required roles
+     * The SECOND role gate in this class, and the reason the `APP_PUBLIC` admission below is repeated
+     * rather than inherited: an ORGANIZATIONS-scoped operation resolves its roles HERE, inside
+     * `validateParentScopeAccess`, and never reaches {@link validateOperationRoles} —
+     * `authorizeCollectionOperation` skips that call for ORGANIZATIONS scope precisely because this
+     * branch has already answered the question. A public declaration honoured at only one of the two
+     * would mean `APP_PUBLIC` worked on APPLICATION-scoped resources and refused on organization-scoped
+     * ones, which is the same defect one scope over.
+     *
+     * The caller has ALREADY proven tenancy by the time this runs — the ORGANIZATIONS branch resolves
+     * an `orgRoleInfo` for this specific organization, and the scope-root branch confines the read
+     * separately — so admitting on a public declaration here grants the right to ASK, never a wider
+     * set of rows.
+     *
+     * @returns true if user has at least one of the required roles, or the operation declares public
+     *   access (in which case it requires none)
      */
     validateRolesForScope(requiredRoles, userRoles, scope) {
+        if (requiredRolesDeclarePublicAccess(requiredRoles))
+            return true;
         return requiredRoles.some(requiredRole => userRoles.some(userRole => {
             const hierarchy = this.getRoleHierarchy(userRole, scope);
             return hierarchy.includes(requiredRole);