@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

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

@@ -11,14 +11,15 @@ 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 { AuditObservationKind, AuditObservationLossReason, emitAuditObservation, recordAuditObservationLoss, } from "../../../monitoring/observability/audit-observation-emission.backend.js";
 import { isOwnScopeRootResource } from "../../../security/authorizations/scope-root-collection-confinement.backend.js";
 let AuthorizationsBackendService = class AuthorizationsBackendService {
     logger;
@@ -84,14 +85,25 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
                         orgRolesAdded++;
                         this.logDebug('Custom org role added', { roleKey, role: typedRoleDefinition.role, inheritFrom: typedRoleDefinition.inheritFrom, isSystemRole: typedRoleDefinition.isSystemRole });
                         break;
+                    /*
+                     * Skipped, not refused — and the author is told somewhere they will actually read (#425).
+                     *
+                     * Refusing here would turn a silently-inert role into a BOOT FAILURE for any application
+                     * that already ships one, which is why this is a warning. But a warning on a startup path
+                     * is read once and never again, so the role stayed inert with no surviving signal. The
+                     * durable one is `wildo local doctor` → "custom role scopes", which reads
+                     * `shared-lib/src/engine/roles.ts` and names every role this switch would drop, before
+                     * the application is shipped rather than after.
+                     *
+                     * Keep the two log lines: they are what a runtime investigation reads, and they are the
+                     * only evidence for a role table this process received some other way.
+                     */
                     case ResourcePrimaryScope.USER_SELF:
-                        // This scope doesn't have dedicated role configurations
-                        // Log a warning but don't add them
-                        this.logger.warn('Custom role with unsupported scope ignored', { roleKey, scope: typedRoleDefinition.relatedPrimaryScope, message: 'USER_SELF scope does not support custom roles' });
+                        this.logger.warn('Custom role with unsupported scope ignored — the role is INERT', { roleKey, scope: typedRoleDefinition.relatedPrimaryScope, message: 'USER_SELF scope does not support custom roles; `wildo local doctor` reports this before the application ships' });
                         invalidRoles.push(roleKey);
                         break;
                     default:
-                        this.logger.warn('Custom role with unknown scope ignored', { roleKey, scope: typedRoleDefinition.relatedPrimaryScope });
+                        this.logger.warn('Custom role with unknown scope ignored — the role is INERT', { roleKey, scope: typedRoleDefinition.relatedPrimaryScope, message: '`wildo local doctor` reports this before the application ships' });
                         invalidRoles.push(roleKey);
                         break;
                 }
@@ -352,10 +364,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 +409,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 +573,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)}`,
@@ -662,7 +733,7 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      * `USERS` is a self-anchor scope root, so its `resourcePrimaryScope` IS `USER_SELF` and every
      * USERS operation lands here. Without an admission this check made the whole administrative
      * surface self-only: `assign_roles`, `revoke_roles`, `suspend_user`, `unsuspend_user`,
-     * `force_password_reset`, the admin READ and the core UPDATE/DELETE all refused against another
+     * `reactivate_user`, `force_password_reset`, the admin READ and the core UPDATE/DELETE all refused against another
      * user, contradicting both the resource specification and the admin UI that surfaces them as
      * per-row actions.
      *
@@ -912,9 +983,30 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      *
      * Fire-and-forget by construction: no `await`, and the promise's rejection is swallowed. An
      * operator's request must not fail because the audit sink is down, and a fail-closed variant would
-     * hand anyone a way to disable operator support by breaking the sink.
+     * hand anyone a way to disable operator support by breaking the sink. That contract is unchanged
+     * and must stay unchanged.
+     *
+     * ## The loss is COUNTED — added 2026-09-09
+     *
+     * Fire-and-forget was the right trade and it was shipped without the other half: nothing recorded
+     * the drops, so an empty operator-crossing trail read identically whether no operator crossed a
+     * boundary or the audit service had been unbound since boot. That is the property that makes the
+     * evidence worthless, and it is the shape
+     * `.claude/rules/negative-results-require-a-positive-probe.md` names — an empty result is evidence
+     * about the pipeline, never about the world.
+     *
+     * Every emission now goes through {@link emitAuditObservation}, which counts an unavailable
+     * service, a synchronous throw and a rejected promise into `audit_observation_dropped_total` and
+     * logs one throttled `error` line per loss shape. It never throws and never awaits, so the
+     * contract above is preserved exactly — read that seam's header before changing anything here.
+     *
+     * **Do not restore the "`audit_store_failure_total` covers this" reading.** It does not, and that
+     * claim was carried at three sites in this package: that counter lives INSIDE
+     * `AuditLogsBackendService._createAuditLog`, so it only ever sees an emission that reached the
+     * audit service. The three shapes counted here never get that far.
      *
      * assurance-control: WILDO.ACCESS.CROSS_TENANT_ADMINISTRATION
+     * assurance-control: WILDO.AUDIT.SECURITY_EVENT — the loss of this evidence is itself detectable.
      */
     recordCrossTenantAdministrativeAccess(resourceObject, resourceIdentifier, executionContext) {
         const operation = executionContext.operation;
@@ -932,10 +1024,12 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
         // absent, so the CALL throws a TypeError synchronously — before any `.catch()` can make it
         // fire-and-forget. It is not a test-only concern either; a host binding an older audit service
         // takes the same throw. An observer must never be able to fail the request it observes.
-        if (typeof auditLogsService?.logCrossTenantAdministrativeAccess !== 'function')
-            return;
-        try {
-            void auditLogsService.logCrossTenantAdministrativeAccess({
+        //
+        // The detection now decides an ARGUMENT rather than an early return: handing the seam
+        // `undefined` is how this site reports `SERVICE_UNAVAILABLE`, which is precisely the loss shape
+        // that used to leave nothing behind at all. Returning early here would restore the silence.
+        const emit = typeof auditLogsService?.logCrossTenantAdministrativeAccess === 'function'
+            ? () => auditLogsService.logCrossTenantAdministrativeAccess({
                 operatorUserId: executionContext.initiatorIds?.userId,
                 targetOrganizationId: rowOrganizationId,
                 resourceType: resourceIdentifier,
@@ -947,11 +1041,23 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
                 admissionDeclared: operation.admitsCrossTenantPlatformAdministration === true,
                 initiatorRoles: initiatorRoles.flatMap(roleInfo => roleInfo.roles ?? []),
                 executionType: executionContext.executionType,
-            })?.catch?.(() => undefined);
-        }
-        catch {
-            // Deliberately swallowed — see the feature-detection note above.
-        }
+            })
+            : undefined;
+        emitAuditObservation({
+            observation: AuditObservationKind.CROSS_TENANT_ADMINISTRATIVE_ACCESS,
+            emit,
+            metricsService: this.resolveMetricsService(),
+            logger: this.logger,
+            // Enough to name WHICH crossing went unrecorded, so a reviewer can reconstruct it from the
+            // application log rather than knowing only that "a crossing, somewhere" was lost. The operator
+            // and the tenant are the two identities the audit row itself would have carried.
+            context: {
+                observedResourceType: resourceIdentifier,
+                observedOperationIdentifier: String(operation.operationIdentifier ?? ''),
+                observedTargetOrganizationId: rowOrganizationId,
+                observedOperatorUserId: executionContext.initiatorIds?.userId,
+            },
+        });
     }
     /**
      * Refuse a per-instance tenant-boundary denial in a way that is INDISTINGUISHABLE from a row that
@@ -1074,10 +1180,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) {
@@ -1104,6 +1265,29 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
                 throw error;
             }
         }
+        /*
+         * An APPLICATION-scoped read can still cross a TENANT boundary, and until now nothing said so.
+         *
+         * `CROSS_TENANT_ADMINISTRATIVE_ACCESS` is emitted from `authorizeOrganizations`, so a row
+         * carrying an `organizationId` that is reached through an APPLICATION-scoped resource — by a
+         * caller holding no organization-wide entry for that tenant — was an unaudited crossing. The
+         * application-scoped audit door (#317) is the case that forced this: its whole purpose is to
+         * return rows from every tenant, and the audit trail is the worst possible surface on which to
+         * make an operator read invisible. `administrative-continuity-floors.md` requires every crossing
+         * to be NAMED in the trail.
+         *
+         * Placed at the SCOPE boundary rather than on that one resource on purpose. The invariant is
+         * "a tenant-attributed row reached by a non-member is a crossing", which is a property of the
+         * ROW and the CALLER, not of one resource — wiring it per-resource is the shape
+         * `invariant-call-site-enumeration.md` exists to prevent, and the next application-scoped
+         * resource carrying an `organizationId` would silently miss it.
+         *
+         * Cheap and non-invasive by construction: the emitter returns immediately when the row carries
+         * no organization (the common case — an application-scoped row is not a crossing), and again
+         * when the caller does hold an organization-wide entry for it. It is fire-and-forget and
+         * feature-detected, so it can neither fail nor slow the request it observes.
+         */
+        this.recordCrossTenantAdministrativeAccess(resourceObject, resourceIdentifier, executionContext);
     }
     /**
      * Authorize ANONYMOUS scope — ownership check via anonymousUserId.
@@ -1130,6 +1314,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
@@ -1182,6 +1389,30 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
             return undefined;
         return this.container.get(SAAS_SERVICE_TYPES.AuditLogsService);
     }
+    /**
+     * Lazy getter for the metrics recorder behind {@link emitAuditObservation}'s loss counter.
+     *
+     * Resolved from the container rather than constructor-injected for the SAME reason the audit
+     * service is (see the `container` param's JSDoc) — but a weaker one: `MetricsService` has a
+     * zero-argument constructor and closes no dependency cycle. What the lazy form actually buys is
+     * that every partial-container test and every positional construction keeps working unchanged,
+     * which is the property this class's whole optional-dependency tail is built around.
+     *
+     * Wrapped, because this runs on the observation path: a container that throws while resolving a
+     * binding must not be able to fail the request the observation is about. Returning `undefined`
+     * degrades the loss signal to its log channel, which is the correct direction — an observability
+     * gap is never a reason to refuse.
+     */
+    resolveMetricsService() {
+        try {
+            if (!this.container?.isBound(SAAS_SERVICE_TYPES.MetricsService))
+                return undefined;
+            return this.container.get(SAAS_SERVICE_TYPES.MetricsService);
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Record a refusal as a `RESOURCE_OPERATION_DENIED` audit event.
      *
@@ -1211,15 +1442,32 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
      * ## Never affects the outcome
      *
      * Every path here is swallowed. The caller has already been correctly refused; an audit-store
-     * problem must not convert that clean refusal into a 500. Detection of a lost row is the audit
-     * pipeline's own control (`audit_store_failure_total`), not this gate's.
+     * problem must not convert that clean refusal into a 500. That stays true.
+     *
+     * ## But the swallow is now COUNTED — corrected 2026-09-09
+     *
+     * This paragraph used to end "detection of a lost row is the audit pipeline's own control
+     * (`audit_store_failure_total`), not this gate's", and that was **false for the shape this method
+     * loses most often**. That counter lives inside `AuditLogsBackendService._createAuditLog`, so it
+     * only ever sees an emission that reached the audit service. When the service is unbound — a
+     * partial DI binding, a host binding an older audit service — this method returned in silence and
+     * NOTHING anywhere recorded that every refusal in the deployment was going unaudited.
+     *
+     * Both exits now report into `audit_observation_dropped_total` via `recordAuditObservationLoss`.
+     * Three paths deliberately do NOT: an absent `operation` (nothing was owed), the `AUDIT_LOGS`
+     * recursion guard, and a dedup decision of `shouldEmit: false`. Each is a suppression the design
+     * asked for, and a loss counter that fires on correct behaviour is one operators learn to ignore.
      *
      * assurance-control: WILDO.ACCESS.AUTHORIZATION_DECISION_AUDIT — the negative access decision is
      * recorded, attributable, and carries the authority context needed to review it.
+     * assurance-control: WILDO.AUDIT.SECURITY_EVENT — and its LOSS is detectable rather than silent.
      */
     async emitAuthorizationDenialAudit(denialReason, operation, executionContext, attemptedResourceIds) {
-        const auditLogsService = this.resolveAuditLogsService();
-        if (!auditLogsService || !operation)
+        // `!operation` is NOT a loss — there is nothing to record, so counting it would fire the loss
+        // signal on a correct path and train a reader to skim past the lines that mean something. The
+        // same reasoning excludes the recursion guard and the dedup decision below: both are DELIBERATE
+        // suppressions of an emission that was never owed, not evidence that went missing.
+        if (!operation)
             return;
         // Defence-in-depth against an emission loop. Structurally unreachable today — the audit write
         // runs as a REPOSITORY_ONLY super-admin context and repository writes do not route through this
@@ -1227,8 +1475,33 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
         // subsystem already carries a documented recursion hazard of exactly that shape (a per-org SIEM
         // dispatch's own config load is a system read that re-enters the audit path). Stateless and
         // concurrency-safe, unlike an in-flight instance flag.
+        //
+        // ORDER: this sits ABOVE the service resolution deliberately, and a first cut had it below —
+        // caught by its own calibration pin. A refusal on the audit resource is owed NO emission, so
+        // reaching the service resolution first would report a `SERVICE_UNAVAILABLE` loss for evidence
+        // that was never going to be written. A loss counter that fires on correct behaviour is one
+        // operators learn to ignore, which would defeat the counter's entire purpose.
         if (operation.resourceIdentifier === CoreResourceType.AUDIT_LOGS)
             return;
+        const auditLogsService = this.resolveAuditLogsService();
+        // Feature-detected for the same reason its cross-tenant sibling is (adding a `log*` method
+        // breaks partially-mocked doubles), and reported for the same reason: an unbound service is the
+        // loss shape that used to leave nothing behind — `_createAuditLog` is never reached, so
+        // `audit_store_failure_total` never fires either.
+        if (typeof auditLogsService?.logResourceOperationDenied !== 'function') {
+            recordAuditObservationLoss({
+                observation: AuditObservationKind.AUTHORIZATION_DENIAL,
+                reason: AuditObservationLossReason.SERVICE_UNAVAILABLE,
+                metricsService: this.resolveMetricsService(),
+                logger: this.logger,
+                context: {
+                    observedResourceType: String(operation.resourceIdentifier),
+                    observedOperationIdentifier: String(operation.operationIdentifier),
+                    observedDenialReason: denialReason,
+                },
+            });
+            return;
+        }
         try {
             const principalUserId = executionContext.initiatorIds?.userId;
             const decision = await resolveDenialAuditEmissionDecision({ redisService: this.redisService, logger: this.logger }, {
@@ -1278,6 +1551,26 @@ let AuthorizationsBackendService = class AuthorizationsBackendService {
                 denialReason,
                 ...projectCaughtErrorLogFields(error),
             });
+            // The warn line above names the ONE refusal whose evidence was lost; this names the RATE. A
+            // per-occurrence line cannot answer "has this been happening all afternoon?" and is exactly
+            // what an operator filters out once it repeats — which is how a swallowed emission stays
+            // swallowed while looking observed.
+            //
+            // `EMISSION_THREW` rather than `EMISSION_REJECTED`: this path `await`s, so a rejected promise
+            // and a synchronous throw arrive at the same `catch` and cannot be told apart here. Claiming
+            // the more specific one would be a distinction the code cannot actually make.
+            recordAuditObservationLoss({
+                observation: AuditObservationKind.AUTHORIZATION_DENIAL,
+                reason: AuditObservationLossReason.EMISSION_THREW,
+                metricsService: this.resolveMetricsService(),
+                logger: this.logger,
+                error,
+                context: {
+                    observedResourceType: String(operation.resourceIdentifier),
+                    observedOperationIdentifier: String(operation.operationIdentifier),
+                    observedDenialReason: denialReason,
+                },
+            });
         }
     }
     /**
@@ -1313,6 +1606,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 +1817,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 +1870,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 +2125,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);