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

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

@@ -19,6 +19,7 @@ import { describeCaughtError, projectCaughtErrorLogFields } from "../../../error
 import { RepositoriesRegistryHandlerBackendService } from "../../../base-classes/services/repositories/repositories-registry-handler.backend.service.js";
 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;
                 }
@@ -721,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.
      *
@@ -971,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;
@@ -991,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,
@@ -1006,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
@@ -1218,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.
@@ -1319,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.
      *
@@ -1348,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
@@ -1364,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 }, {
@@ -1415,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,
+                },
+            });
         }
     }
     /**