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

package/dist/esm/security/authorizations/platform-access-grant-custom-implementation.backend.service.js

@@ -11,11 +11,10 @@
  * That is also why the resource exposes no generic CREATE or UPDATE door: a second write path would
  * be a second way to mint an elevation, which is the one thing this resource exists to prevent.
  */
-import { CoreResourceType, ErrorCustomMessageReference, ErrorType, PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES, PlatformAccessGrantAutoApprovalReason, PlatformAccessGrantLifecycleTransition, PlatformAccessGrantStatus, PlatformAccessGrants_Operations, ResourceOperationVariantType, resolvePlatformAccessGrantExpiry, } from '@wildo-ai/saas-models';
+import { CoreResourceType, ErrorCustomMessageReference, ErrorType, PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES, PlatformAccessGrantAutoApprovalReason, PlatformAccessGrantLifecycleTransition, PlatformAccessGrantScope, PlatformAccessGrantStatus, PlatformAccessGrants_Operations, ResourceOperationVariantType, resolvePlatformAccessGrantExpiry, } from '@wildo-ai/saas-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
-import { registerTransactionPostCommitEffect } from '../../databases/models/transaction.shared.schemas.js';
-import { describeCaughtError } from '../../errors/utils/error-log-level-classification.backend.utils.js';
-import { AuditObservationKind, AuditObservationLossReason, recordAuditObservationLoss, } from '../../monitoring/observability/audit-observation-emission.backend.js';
+import { recordAccessGrantTransition } from '../../security/authorizations/access-grant-lifecycle-audit.backend.js';
+import { createAccessGrantDecisionFactory } from '../../security/authorizations/access-grant-decision.factory.backend.js';
 import { createResourceCustomServiceImplementation } from '../../base-classes/services/services/resource-operation-custom-implementation.factory.backend.js';
 import { createOrganizationOwnerConferralResolver, createOrganizationOwnerFloorPopulationContext, measureUsableOrganizationOwners, } from '../../security/authorizations/organization-owner-floor.backend.utils.js';
 /**
@@ -44,112 +43,16 @@ async function tenantHasAnApprover(params) {
     return usableOwners.length > 0;
 }
 /**
- * Record one grant transition, AFTER the write is durable.
+ * Record one TENANT grant transition.
  *
- * Deferred to commit rather than emitted from the postfix hook directly. A postfix runs INSIDE the
- * declared transaction, so an audit row written there survives a rollback — the trail would then
- * claim an elevation that does not exist, which is worse than no trail at all.
- *
- * Best-effort in every other respect: feature-detected against the audit service (adding a `log*`
- * method breaks partially-mocked doubles, and the absent property throws synchronously before any
- * `.catch()` can help) and never allowed to fail the transition it observes.
- *
- * ## The loss is COUNTED — added 2026-09-09
- *
- * Both best-effort exits used to be quiet in the way that matters. The `catch` logged one line per
- * occurrence, which cannot answer "has this been failing all afternoon?"; the unbound-service and
- * absent-method exits logged nothing at all, and `audit_store_failure_total` cannot see them either
- * (it fires inside `_createAuditLog`, which those paths never reach). So a grant trail with no
- * transitions in it read identically whether no elevation was requested or the audit service had
- * been unbound since boot — and for THIS resource that is the whole evidentiary claim: an elevation
- * with no recorded request and approval is a standing privilege wearing a lifecycle's clothes.
- *
- * `recordAuditObservationLoss` now counts every exit into `audit_observation_dropped_total` and
- * emits one throttled `error` line per loss shape. It never throws, so best-effort is preserved.
+ * A thin binding of {@link recordAccessGrantTransition} with this resource's scope. The emitter — the
+ * post-commit deferral, the feature detection, the loss accounting — moved to
+ * `access-grant-lifecycle-audit.backend.ts` on 2026-09-09 when the application-wide grant arrived,
+ * because two near-copies of it would have drifted on exactly the parts that make the trail complete.
+ * Nothing about the behaviour changed; see that module for the reasoning behind each half.
  */
 function recordGrantTransition(params) {
-    /**
-     * The metrics recorder behind the loss counter, or `undefined` when nothing is bound.
-     *
-     * Wrapped: this runs on the observation path, so a container that throws while resolving must not
-     * be able to fail the transition. Losing the metric channel degrades the signal to its log line,
-     * which is the correct direction — an observability gap is never a reason to refuse.
-     */
-    const resolveMetricsService = () => {
-        try {
-            if (!params.container.isBound?.(SAAS_SERVICE_TYPES.MetricsService))
-                return undefined;
-            return params.container.get(SAAS_SERVICE_TYPES.MetricsService);
-        }
-        catch {
-            return undefined;
-        }
-    };
-    const reportLoss = (reason, error) => recordAuditObservationLoss({
-        observation: AuditObservationKind.PLATFORM_ACCESS_GRANT_LIFECYCLE,
-        reason,
-        metricsService: resolveMetricsService(),
-        logger: params.utils.logger,
-        error,
-        // Names WHICH transition on WHICH grant went unrecorded, so the gap can be reconstructed from
-        // the grant row rather than being known only as "a transition, somewhere".
-        context: {
-            observedTransition: params.transition,
-            observedGrantId: String(params.grant._id ?? ''),
-            observedTargetOrganizationId: String(params.grant.organizationId ?? ''),
-        },
-    });
-    const emit = async () => {
-        try {
-            // One report for both halves of "the audit service cannot take this": an unbound service and a
-            // bound service missing the method are the same loss to a reviewer, and splitting them would
-            // add a metric label nobody could act on differently.
-            if (!params.container.isBound?.(SAAS_SERVICE_TYPES.AuditLogsService)) {
-                reportLoss(AuditObservationLossReason.SERVICE_UNAVAILABLE);
-                return;
-            }
-            const auditLogsService = params.container.get(SAAS_SERVICE_TYPES.AuditLogsService);
-            if (typeof auditLogsService?.logPlatformAccessGrantLifecycle !== 'function') {
-                reportLoss(AuditObservationLossReason.SERVICE_UNAVAILABLE);
-                return;
-            }
-            const grant = params.grant;
-            await auditLogsService.logPlatformAccessGrantLifecycle({
-                transition: params.transition,
-                grantId: String(grant._id ?? ''),
-                targetOrganizationId: String(grant.organizationId ?? ''),
-                operatorUserId: String(grant.operatorUserId ?? ''),
-                justification: grant.justification,
-                resultingStatus: grant.status,
-                expiresAt: grant.expiresAt,
-                autoApprovalReason: grant.autoApprovalReason,
-                decidedByUserId: params.decidedByUserId,
-                decisionReason: grant.decisionReason,
-            });
-        }
-        catch (error) {
-            params.utils.logger?.error?.('Failed to record a platform-access-grant lifecycle event', {
-                reason: 'platform_access_grant_lifecycle_audit_emission_failed',
-                transition: params.transition,
-                error: describeCaughtError(error),
-            });
-            // The line above names ONE lost transition; this names the RATE, on the same counter every
-            // other dropped security observation lands on. `EMISSION_THREW`: this path `await`s, so a
-            // rejection and a synchronous throw arrive at the same `catch` and cannot be told apart —
-            // claiming the more specific member would be a distinction the code cannot make.
-            reportLoss(AuditObservationLossReason.EMISSION_THREW, error);
-        }
-    };
-    const transaction = params.utils.serviceOptions?.transaction;
-    if (transaction) {
-        registerTransactionPostCommitEffect(transaction, {
-            key: `platform-access-grant:${params.transition}:${String(params.grant._id ?? '')}`,
-            execute: emit,
-        });
-    }
-    else {
-        void emit();
-    }
+    recordAccessGrantTransition({ ...params, grantScope: PlatformAccessGrantScope.TENANT });
 }
 export function createPlatformAccessGrantFactories() {
     /**
@@ -250,82 +153,18 @@ export function createPlatformAccessGrantFactories() {
         });
     };
     /**
-     * The three decision verbs share a shape: refuse unless the current status permits the transition,
-     * then write exactly the fields that transition owns.
+     * The decision verbs. The shape moved to `access-grant-decision.factory.backend.ts` on 2026-09-09,
+     * when the application-wide grant needed the same four transitions plus one refusal of its own; the
+     * behaviour of every verb below is unchanged, and its reasoning lives in that module.
      *
-     * `enabledCondition` on the operation config already gates each verb, but that guard is evaluated
-     * against the row the framework fetched and is a UI-and-dispatch concern. Re-checking here is the
-     * fail-closed half: a custom implementation is addressed by an exact operation path and inherits
-     * nothing, so a future variant added without an `enabledCondition` would otherwise transition a
-     * terminal grant silently.
+     * No `additionalPrecondition` here on purpose. The application-wide `approve` refuses a
+     * self-approval; this one has no equivalent because the requester is a PLATFORM operator and the
+     * approver is a TENANT administrator gated on `CORE_ORG_ROLES.ORG_ADMIN` with no cross-tenant
+     * admission — they cannot be the same principal, and the ABSENCE of that admission is what makes it
+     * so. Adding a same-person check here would look like defence in depth and would in fact be a
+     * second, weaker statement of a control the operation config already carries absolutely.
      */
-    const makeDecisionFactory = (
-    // The whole enum rather than a three-member union: `ResourceConfiguration_OperationPath` does not
-    // accept a union of enum members, and narrowing it here would buy nothing — the three call sites
-    // below are the only ones and each names its verb explicitly.
-    operationIdentifier, options) => (_resourcesRegistryService, container) => {
-        const containerRef = container;
-        return createResourceCustomServiceImplementation({
-            operationPath: {
-                resourceIdentifier: CoreResourceType.PLATFORM_ACCESS_GRANTS,
-                operationIdentifier,
-                variantType: options.variantType ?? ResourceOperationVariantType.API_CALL,
-                isOperationDefault: true,
-            },
-            debugLabel: options.debugLabel,
-            authoritativeFields: options.stampsApprover
-                ? ['status', 'approvedByUserId', 'approvedAt', 'decisionReason']
-                : ['status', 'decisionReason'],
-            transactionalCore: true,
-            // No additional participants: a decision writes only the grant row itself, which the operation
-            // resource contributes automatically. Declaring the set explicitly (even as empty) is the
-            // authoring contract — startup proves adapter compatibility for what is declared, and it cannot
-            // detect an omitted participant.
-            transactionParticipants: {},
-            handlers: {
-                prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
-                    const currentObject = utils.currentObject;
-                    const currentStatus = currentObject?.status;
-                    if (!currentStatus || !options.permittedFrom.includes(currentStatus)) {
-                        throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
-                            customMessageReference: ErrorCustomMessageReference.CONFLICT,
-                            context: {
-                                reason: 'platform_access_grant_transition_not_permitted_from_current_status',
-                                currentStatus: currentStatus ?? null,
-                                permittedFrom: [...options.permittedFrom],
-                                operationIdentifier,
-                            },
-                        });
-                    }
-                    const decisionReason = input?.decisionReason;
-                    const now = new Date();
-                    return {
-                        status: options.nextStatus,
-                        ...(decisionReason ? { decisionReason } : {}),
-                        // Only an APPROVAL names a human approver. A revocation or a denial is a decision too,
-                        // but recording either in `approvedByUserId` would corrupt the one field an audit reads
-                        // to answer "did somebody in the tenant say yes?".
-                        ...(options.stampsApprover
-                            ? { approvedByUserId: executionContext.initiatorIds?.userId, approvedAt: now }
-                            : {}),
-                    };
-                },
-                postfixCoreOperations: async (_id, updatedGrant, executionContext, _operationPath, utils) => {
-                    recordGrantTransition({
-                        container: containerRef,
-                        utils,
-                        transition: options.auditTransition,
-                        grant: (updatedGrant ?? {}),
-                        // The tenant administrator who acted — distinct from the grant's `operatorUserId`, which
-                        // stays the operator who asked. Conflating them would make an audit unable to answer who
-                        // said yes.
-                        decidedByUserId: executionContext.initiatorIds?.userId,
-                    });
-                    return updatedGrant;
-                },
-            },
-        });
-    };
+    const makeDecisionFactory = (operationIdentifier, options) => createAccessGrantDecisionFactory(CoreResourceType.PLATFORM_ACCESS_GRANTS, PlatformAccessGrantScope.TENANT, operationIdentifier, { ...options, transitionRefusalReason: 'platform_access_grant_transition_not_permitted_from_current_status' });
     return [
         requestAccessFactory,
         makeDecisionFactory(PlatformAccessGrants_Operations.APPROVE, {

package/dist/esm/security/authorizations/platform-access-grant-custom-implementation.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform-access-grant-custom-implementation.backend.service.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/platform-access-grant-custom-implementation.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Platform access grants — the four lifecycle transitions.\n *\n * The whole resource exists to turn a STANDING platform privilege into a requested, justified,\n * tenant-scoped, self-expiring one (rungs 4–5 of the ladder in\n * `.claude/rules/administrative-continuity-floors.md`). These implementations are where the fields\n * that carry that guarantee — `operatorUserId`, `status`, `expiresAt`, `approvedByUserId` — are\n * AUTHORED BY THE SERVER. Every one of them is `.excludeFromCreate()` / `.excludeFromUpdate()`, so a\n * client cannot supply them; the strict request DTO drops them and these prefixes put them back.\n *\n * That is also why the resource exposes no generic CREATE or UPDATE door: a second write path would\n * be a second way to mint an elevation, which is the one thing this resource exists to prevent.\n */\n\nimport type { Container } from 'inversify';\nimport {\n  CoreResourceOperation,\n  CoreResourceType,\n  ErrorCustomMessageReference,\n  ErrorType,\n  PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES,\n  PlatformAccessGrantAutoApprovalReason,\n  PlatformAccessGrantLifecycleTransition,\n  PlatformAccessGrantStatus,\n  PlatformAccessGrants_Operations,\n  ResourceOperationVariantType,\n  resolvePlatformAccessGrantExpiry,\n} from '@wildo-ai/saas-models';\nimport type { Organization, PlatformAccessGrant } from '@wildo-ai/saas-models';\n\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { registerTransactionPostCommitEffect } from '~wildo-backend-lib/databases/models/transaction.shared.schemas';\nimport { describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport {\n  AuditObservationKind,\n  AuditObservationLossReason,\n  recordAuditObservationLoss,\n  type AuditObservationLossMetricsRecorder,\n} from '~wildo-backend-lib/monitoring/observability/audit-observation-emission.backend';\nimport type { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';\nimport { createResourceCustomServiceImplementation } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourceCustomServiceImplementationFactory } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { AuthExecutionContextFactoryBackendService } from '~wildo-backend-lib/security/authentications/services/auth-execution-context-factory.backend.service';\nimport type { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport {\n  createOrganizationOwnerConferralResolver,\n  createOrganizationOwnerFloorPopulationContext,\n  measureUsableOrganizationOwners,\n} from '~wildo-backend-lib/security/authorizations/organization-owner-floor.backend.utils';\n\n/**\n * Can this tenant currently supply a human who could approve?\n *\n * Deliberately delegates to {@link measureUsableOrganizationOwners} — the OWNER FLOOR's own\n * measurement — rather than asking a similar-looking question here. The floor already answers\n * \"does this tenant have an administratively usable owner?\" across three axes (the role confers\n * ownership through the live table, the membership is ACTIVE, and the linked user is ACTIVE), and a\n * second implementation would drift from it the first time any axis changed.\n *\n * Drift here would be quiet and bad in both directions: over-counting makes a stranded tenant wait\n * forever for an approver who cannot act, and under-counting auto-approves operator access into a\n * tenant that could have consented.\n */\nasync function tenantHasAnApprover(params: {\n  organizationId: string;\n  authEcFactory: AuthExecutionContextFactoryBackendService;\n  conferringRoles: readonly string[];\n  repositoriesRegistry: RepositoriesRegistryHandlerBackendService;\n  errorBuilder: ErrorBuilderBackendService;\n}): Promise<boolean> {\n  const executionContext = await createOrganizationOwnerFloorPopulationContext(params.authEcFactory);\n  const usableOwners = await measureUsableOrganizationOwners({\n    organizationId: params.organizationId,\n    executionContext,\n    repositoriesRegistry: params.repositoriesRegistry,\n    errorBuilder: params.errorBuilder,\n    conferringRoles: params.conferringRoles,\n    operationIdentifier: PlatformAccessGrants_Operations.REQUEST_ACCESS,\n  });\n  return usableOwners.length > 0;\n}\n\n/**\n * Record one grant transition, AFTER the write is durable.\n *\n * Deferred to commit rather than emitted from the postfix hook directly. A postfix runs INSIDE the\n * declared transaction, so an audit row written there survives a rollback — the trail would then\n * claim an elevation that does not exist, which is worse than no trail at all.\n *\n * Best-effort in every other respect: feature-detected against the audit service (adding a `log*`\n * method breaks partially-mocked doubles, and the absent property throws synchronously before any\n * `.catch()` can help) and never allowed to fail the transition it observes.\n *\n * ## The loss is COUNTED — added 2026-09-09\n *\n * Both best-effort exits used to be quiet in the way that matters. The `catch` logged one line per\n * occurrence, which cannot answer \"has this been failing all afternoon?\"; the unbound-service and\n * absent-method exits logged nothing at all, and `audit_store_failure_total` cannot see them either\n * (it fires inside `_createAuditLog`, which those paths never reach). So a grant trail with no\n * transitions in it read identically whether no elevation was requested or the audit service had\n * been unbound since boot — and for THIS resource that is the whole evidentiary claim: an elevation\n * with no recorded request and approval is a standing privilege wearing a lifecycle's clothes.\n *\n * `recordAuditObservationLoss` now counts every exit into `audit_observation_dropped_total` and\n * emits one throttled `error` line per loss shape. It never throws, so best-effort is preserved.\n */\nfunction recordGrantTransition(params: {\n  container: Container;\n  utils: { serviceOptions?: { transaction?: unknown }; logger?: { error?: (message: string, meta: unknown) => void } };\n  transition: PlatformAccessGrantLifecycleTransition;\n  grant: Record<string, unknown>;\n  decidedByUserId?: string;\n}): void {\n  /**\n   * The metrics recorder behind the loss counter, or `undefined` when nothing is bound.\n   *\n   * Wrapped: this runs on the observation path, so a container that throws while resolving must not\n   * be able to fail the transition. Losing the metric channel degrades the signal to its log line,\n   * which is the correct direction — an observability gap is never a reason to refuse.\n   */\n  const resolveMetricsService = (): AuditObservationLossMetricsRecorder | undefined => {\n    try {\n      if (!params.container.isBound?.(SAAS_SERVICE_TYPES.MetricsService)) return undefined;\n      return params.container.get<AuditObservationLossMetricsRecorder>(SAAS_SERVICE_TYPES.MetricsService);\n    } catch {\n      return undefined;\n    }\n  };\n\n  const reportLoss = (reason: AuditObservationLossReason, error?: unknown): void =>\n    recordAuditObservationLoss({\n      observation: AuditObservationKind.PLATFORM_ACCESS_GRANT_LIFECYCLE,\n      reason,\n      metricsService: resolveMetricsService(),\n      logger: params.utils.logger,\n      error,\n      // Names WHICH transition on WHICH grant went unrecorded, so the gap can be reconstructed from\n      // the grant row rather than being known only as \"a transition, somewhere\".\n      context: {\n        observedTransition: params.transition,\n        observedGrantId: String(params.grant._id ?? ''),\n        observedTargetOrganizationId: String(params.grant.organizationId ?? ''),\n      },\n    });\n\n  const emit = async (): Promise<void> => {\n    try {\n      // One report for both halves of \"the audit service cannot take this\": an unbound service and a\n      // bound service missing the method are the same loss to a reviewer, and splitting them would\n      // add a metric label nobody could act on differently.\n      if (!params.container.isBound?.(SAAS_SERVICE_TYPES.AuditLogsService)) {\n        reportLoss(AuditObservationLossReason.SERVICE_UNAVAILABLE);\n        return;\n      }\n      const auditLogsService = params.container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService);\n      if (typeof auditLogsService?.logPlatformAccessGrantLifecycle !== 'function') {\n        reportLoss(AuditObservationLossReason.SERVICE_UNAVAILABLE);\n        return;\n      }\n\n      const grant = params.grant;\n      await auditLogsService.logPlatformAccessGrantLifecycle({\n        transition: params.transition,\n        grantId: String(grant._id ?? ''),\n        targetOrganizationId: String(grant.organizationId ?? ''),\n        operatorUserId: String(grant.operatorUserId ?? ''),\n        justification: grant.justification as string | undefined,\n        resultingStatus: grant.status as PlatformAccessGrantStatus,\n        expiresAt: grant.expiresAt as Date | undefined,\n        autoApprovalReason: grant.autoApprovalReason as PlatformAccessGrantAutoApprovalReason | undefined,\n        decidedByUserId: params.decidedByUserId,\n        decisionReason: grant.decisionReason as string | undefined,\n      });\n    } catch (error) {\n      params.utils.logger?.error?.('Failed to record a platform-access-grant lifecycle event', {\n        reason: 'platform_access_grant_lifecycle_audit_emission_failed',\n        transition: params.transition,\n        error: describeCaughtError(error),\n      });\n      // The line above names ONE lost transition; this names the RATE, on the same counter every\n      // other dropped security observation lands on. `EMISSION_THREW`: this path `await`s, so a\n      // rejection and a synchronous throw arrive at the same `catch` and cannot be told apart —\n      // claiming the more specific member would be a distinction the code cannot make.\n      reportLoss(AuditObservationLossReason.EMISSION_THREW, error);\n    }\n  };\n\n  const transaction = params.utils.serviceOptions?.transaction;\n  if (transaction) {\n    registerTransactionPostCommitEffect(transaction as never, {\n      key: `platform-access-grant:${params.transition}:${String(params.grant._id ?? '')}`,\n      execute: emit,\n    });\n  } else {\n    void emit();\n  }\n}\n\nexport function createPlatformAccessGrantFactories(): ResourceCustomServiceImplementationFactory[] {\n  /**\n   * REQUEST — the bootstrap verb, and the only one reachable without an existing grant.\n   *\n   * Requesting is not accessing: this writes one row and touches nothing else in the tenant, which is\n   * what makes the exemption safe when the admission predicate starts requiring a grant (Step 4).\n   */\n  const requestAccessFactory = (\n    _resourcesRegistryService: ResourcesRegistryBackendService,\n    container: Container,\n  ) => {\n    const authEcFactory = container.get<AuthExecutionContextFactoryBackendService>(SAAS_SERVICE_TYPES.AuthExecutionContextFactory);\n    const organizationOwnerConferralResolver = createOrganizationOwnerConferralResolver(container);\n    return createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.PLATFORM_ACCESS_GRANTS,\n        operationIdentifier: PlatformAccessGrants_Operations.REQUEST_ACCESS,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'platform-access-grants.request-access.api',\n      // Every one of these is `.excludeFromCreate()`, so the strict request DTO drops whatever a\n      // caller sent and the prefix's value is authoritative. Declaring them makes that explicit\n      // rather than inferred — the inference has a hole for callers that reach the service tier with\n      // the key already present (MCP `callTool` forwards arguments unparsed), and on THIS resource a\n      // caller choosing their own `status` or `expiresAt` would defeat the entire mechanism.\n      authoritativeFields: ['operatorUserId', 'status', 'expiresAt', 'autoApprovalReason', 'approvedAt'],\n      transactionalCore: true,\n      transactionParticipants: { targetOrganization: CoreResourceType.ORGANIZATIONS },\n      handlers: {\n        prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n          const payload = input as { justification?: string; requestedDurationMinutes?: number };\n          // The primary-scope URL is the one target authority. The execution-context creator has\n          // already validated the mandatory `organizationId` path parameter and placed it here;\n          // reading a second body value would make callers author the security boundary twice and\n          // would preserve an unnecessary path/body mismatch state.\n          const organizationId = executionContext.organizationId;\n          const operatorUserId = executionContext.initiatorIds?.userId;\n\n          if (!organizationId || !operatorUserId) {\n            throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n              customMessageReference: ErrorCustomMessageReference.VALIDATION,\n              context: { reason: 'platform_access_grant_requires_target_and_operator' },\n            });\n          }\n\n          // Read the tenant's posture in the same unit of work as the write. Reading it outside the\n          // transaction would let a tenant that just switched Lockbox ON have a request slip through\n          // as auto-approved.\n          // Reuses the floor's own population context rather than inventing an organizations-read\n          // helper: it is already a system context authorized for the tenant-scoped reads this needs,\n          // and adding a second system-context factory for one call site is how two subtly different\n          // privileged contexts start to exist.\n          const systemEc = await createOrganizationOwnerFloorPopulationContext(authEcFactory);\n          const organization = await utils.servicesRegistry.read<Organization>(\n            CoreResourceType.ORGANIZATIONS,\n            systemEc,\n            { _id: organizationId },\n            utils.serviceOptions,\n          );\n          if (!organization) {\n            throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n              customMessageReference: ErrorCustomMessageReference.NOT_FOUND,\n              context: { reason: 'platform_access_grant_target_organization_not_found' },\n            });\n          }\n\n          const now = new Date();\n          const approvalRequired = (organization as { platformAccessApprovalRequired?: boolean }).platformAccessApprovalRequired === true;\n\n          // The circularity guard. A tenant with no administratively usable owner cannot approve\n          // anything, so requiring its approval would make its own repair impossible — the exact\n          // deadlock `organizationMembers.grantOwnership` exists to break. Measured, never assumed,\n          // and never manufacturable by the operator: stranding a tenant is what the floors refuse.\n          const canApprove = approvalRequired\n            ? await tenantHasAnApprover({\n              organizationId,\n              authEcFactory,\n              conferringRoles: organizationOwnerConferralResolver(),\n              repositoriesRegistry: utils.repositoriesRegistry,\n              errorBuilder: utils.errorBuilder,\n            })\n            : false;\n\n          const autoApprovalReason = !approvalRequired\n            ? PlatformAccessGrantAutoApprovalReason.TENANT_APPROVAL_NOT_REQUIRED\n            : (canApprove ? undefined : PlatformAccessGrantAutoApprovalReason.TENANT_CANNOT_APPROVE);\n\n          const status = autoApprovalReason\n            ? PlatformAccessGrantStatus.ACTIVE\n            : PlatformAccessGrantStatus.PENDING_APPROVAL;\n\n          return {\n            organizationId,\n            justification: payload.justification,\n            operatorUserId,\n            status,\n            expiresAt: resolvePlatformAccessGrantExpiry(payload.requestedDurationMinutes, now),\n            ...(autoApprovalReason ? { autoApprovalReason, approvedAt: now } : {}),\n          };\n        },\n        postfixCoreOperations: async (_id, createdGrant, _executionContext, _operationPath, utils) => {\n          recordGrantTransition({\n            container,\n            utils,\n            transition: PlatformAccessGrantLifecycleTransition.REQUESTED,\n            grant: (createdGrant ?? {}) as Record<string, unknown>,\n          });\n          return createdGrant;\n        },\n      },\n    });\n  };\n\n  /**\n   * The three decision verbs share a shape: refuse unless the current status permits the transition,\n   * then write exactly the fields that transition owns.\n   *\n   * `enabledCondition` on the operation config already gates each verb, but that guard is evaluated\n   * against the row the framework fetched and is a UI-and-dispatch concern. Re-checking here is the\n   * fail-closed half: a custom implementation is addressed by an exact operation path and inherits\n   * nothing, so a future variant added without an `enabledCondition` would otherwise transition a\n   * terminal grant silently.\n   */\n  const makeDecisionFactory = (\n    // The whole enum rather than a three-member union: `ResourceConfiguration_OperationPath` does not\n    // accept a union of enum members, and narrowing it here would buy nothing — the three call sites\n    // below are the only ones and each names its verb explicitly.\n    operationIdentifier: PlatformAccessGrants_Operations,\n    options: {\n      debugLabel: string;\n      nextStatus: PlatformAccessGrantStatus;\n      permittedFrom: readonly PlatformAccessGrantStatus[];\n      stampsApprover: boolean;\n      auditTransition: PlatformAccessGrantLifecycleTransition;\n      /**\n       * Defaults to API_CALL — every operator-facing decision. EXPIRE is INTERNAL_CALL, and the\n       * lookup key is built from the RUNNING operation's variant type, so a mismatch here does not\n       * fail loudly: the implementation is simply never found and the core UPDATE runs with no\n       * transition guard and no audit row.\n       */\n      variantType?: ResourceOperationVariantType;\n    },\n  ): ResourceCustomServiceImplementationFactory =>\n    (_resourcesRegistryService: ResourcesRegistryBackendService, container: Container) => {\n    const containerRef = container;\n    return createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.PLATFORM_ACCESS_GRANTS,\n        operationIdentifier,\n        variantType: options.variantType ?? ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: options.debugLabel,\n      authoritativeFields: options.stampsApprover\n        ? ['status', 'approvedByUserId', 'approvedAt', 'decisionReason']\n        : ['status', 'decisionReason'],\n      transactionalCore: true,\n      // No additional participants: a decision writes only the grant row itself, which the operation\n      // resource contributes automatically. Declaring the set explicitly (even as empty) is the\n      // authoring contract — startup proves adapter compatibility for what is declared, and it cannot\n      // detect an omitted participant.\n      transactionParticipants: {},\n      handlers: {\n        prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n          const currentObject = utils.currentObject as Pick<PlatformAccessGrant, 'status'> | undefined;\n          const currentStatus = currentObject?.status;\n\n          if (!currentStatus || !options.permittedFrom.includes(currentStatus)) {\n            throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {\n              customMessageReference: ErrorCustomMessageReference.CONFLICT,\n              context: {\n                reason: 'platform_access_grant_transition_not_permitted_from_current_status',\n                currentStatus: currentStatus ?? null,\n                permittedFrom: [...options.permittedFrom],\n                operationIdentifier,\n              },\n            });\n          }\n\n          const decisionReason = (input as { decisionReason?: string })?.decisionReason;\n          const now = new Date();\n\n          return {\n            status: options.nextStatus,\n            ...(decisionReason ? { decisionReason } : {}),\n            // Only an APPROVAL names a human approver. A revocation or a denial is a decision too,\n            // but recording either in `approvedByUserId` would corrupt the one field an audit reads\n            // to answer \"did somebody in the tenant say yes?\".\n            ...(options.stampsApprover\n              ? { approvedByUserId: executionContext.initiatorIds?.userId, approvedAt: now }\n              : {}),\n          };\n        },\n        postfixCoreOperations: async (_id, updatedGrant, executionContext, _operationPath, utils) => {\n          recordGrantTransition({\n            container: containerRef!,\n            utils,\n            transition: options.auditTransition,\n            grant: (updatedGrant ?? {}) as Record<string, unknown>,\n            // The tenant administrator who acted — distinct from the grant's `operatorUserId`, which\n            // stays the operator who asked. Conflating them would make an audit unable to answer who\n            // said yes.\n            decidedByUserId: executionContext.initiatorIds?.userId,\n          });\n          return updatedGrant;\n        },\n      },\n    });\n  };\n\n  return [\n    requestAccessFactory,\n    makeDecisionFactory(PlatformAccessGrants_Operations.APPROVE, {\n      debugLabel: 'platform-access-grants.approve.api',\n      auditTransition: PlatformAccessGrantLifecycleTransition.APPROVED,\n      nextStatus: PlatformAccessGrantStatus.ACTIVE,\n      permittedFrom: [PlatformAccessGrantStatus.PENDING_APPROVAL],\n      stampsApprover: true,\n    }),\n    makeDecisionFactory(PlatformAccessGrants_Operations.DENY, {\n      debugLabel: 'platform-access-grants.deny.api',\n      auditTransition: PlatformAccessGrantLifecycleTransition.DENIED,\n      nextStatus: PlatformAccessGrantStatus.DENIED,\n      permittedFrom: [PlatformAccessGrantStatus.PENDING_APPROVAL],\n      stampsApprover: false,\n    }),\n    makeDecisionFactory(PlatformAccessGrants_Operations.REVOKE, {\n      debugLabel: 'platform-access-grants.revoke.api',\n      auditTransition: PlatformAccessGrantLifecycleTransition.REVOKED,\n      nextStatus: PlatformAccessGrantStatus.REVOKED,\n      // Both a pending request and a live elevation can be withdrawn; a terminal one cannot be\n      // re-terminated, which would rewrite the decision history.\n      permittedFrom: PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES,\n      stampsApprover: false,\n    }),\n    /**\n     * The one transition with no human actor (#413). Everything else here records a decision\n     * somebody made; this records that a window closed, so `decidedByUserId` resolves to nothing and\n     * that absence is the fact.\n     *\n     * Permitted from ACTIVE alone. A grant the tenant DENIED or REVOKED is terminal and must keep\n     * saying which — relabelling it EXPIRED would rewrite the decision history a customer audit\n     * reads, which is the opposite of why this sweep exists.\n     */\n    makeDecisionFactory(PlatformAccessGrants_Operations.EXPIRE, {\n      debugLabel: 'platform-access-grants.expire.internal',\n      auditTransition: PlatformAccessGrantLifecycleTransition.EXPIRED,\n      nextStatus: PlatformAccessGrantStatus.EXPIRED,\n      permittedFrom: [PlatformAccessGrantStatus.ACTIVE],\n      stampsApprover: false,\n      variantType: ResourceOperationVariantType.INTERNAL_CALL,\n    }),\n  ];\n}\n"]}
+{"version":3,"file":"platform-access-grant-custom-implementation.backend.service.js","sourceRoot":"","sources":["../../../../src/security/authorizations/platform-access-grant-custom-implementation.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Platform access grants — the four lifecycle transitions.\n *\n * The whole resource exists to turn a STANDING platform privilege into a requested, justified,\n * tenant-scoped, self-expiring one (rungs 4–5 of the ladder in\n * `.claude/rules/administrative-continuity-floors.md`). These implementations are where the fields\n * that carry that guarantee — `operatorUserId`, `status`, `expiresAt`, `approvedByUserId` — are\n * AUTHORED BY THE SERVER. Every one of them is `.excludeFromCreate()` / `.excludeFromUpdate()`, so a\n * client cannot supply them; the strict request DTO drops them and these prefixes put them back.\n *\n * That is also why the resource exposes no generic CREATE or UPDATE door: a second write path would\n * be a second way to mint an elevation, which is the one thing this resource exists to prevent.\n */\n\nimport type { Container } from 'inversify';\nimport {\n  CoreResourceOperation,\n  CoreResourceType,\n  ErrorCustomMessageReference,\n  ErrorType,\n  PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES,\n  PlatformAccessGrantAutoApprovalReason,\n  PlatformAccessGrantLifecycleTransition,\n  PlatformAccessGrantScope,\n  PlatformAccessGrantStatus,\n  PlatformAccessGrants_Operations,\n  ResourceOperationVariantType,\n  resolvePlatformAccessGrantExpiry,\n} from '@wildo-ai/saas-models';\nimport type { Organization, PlatformAccessGrant } from '@wildo-ai/saas-models';\n\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { recordAccessGrantTransition } from '~wildo-backend-lib/security/authorizations/access-grant-lifecycle-audit.backend';\nimport { createAccessGrantDecisionFactory } from '~wildo-backend-lib/security/authorizations/access-grant-decision.factory.backend';\nimport { createResourceCustomServiceImplementation } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourceCustomServiceImplementationFactory } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { AuthExecutionContextFactoryBackendService } from '~wildo-backend-lib/security/authentications/services/auth-execution-context-factory.backend.service';\nimport type { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport {\n  createOrganizationOwnerConferralResolver,\n  createOrganizationOwnerFloorPopulationContext,\n  measureUsableOrganizationOwners,\n} from '~wildo-backend-lib/security/authorizations/organization-owner-floor.backend.utils';\n\n/**\n * Can this tenant currently supply a human who could approve?\n *\n * Deliberately delegates to {@link measureUsableOrganizationOwners} — the OWNER FLOOR's own\n * measurement — rather than asking a similar-looking question here. The floor already answers\n * \"does this tenant have an administratively usable owner?\" across three axes (the role confers\n * ownership through the live table, the membership is ACTIVE, and the linked user is ACTIVE), and a\n * second implementation would drift from it the first time any axis changed.\n *\n * Drift here would be quiet and bad in both directions: over-counting makes a stranded tenant wait\n * forever for an approver who cannot act, and under-counting auto-approves operator access into a\n * tenant that could have consented.\n */\nasync function tenantHasAnApprover(params: {\n  organizationId: string;\n  authEcFactory: AuthExecutionContextFactoryBackendService;\n  conferringRoles: readonly string[];\n  repositoriesRegistry: RepositoriesRegistryHandlerBackendService;\n  errorBuilder: ErrorBuilderBackendService;\n}): Promise<boolean> {\n  const executionContext = await createOrganizationOwnerFloorPopulationContext(params.authEcFactory);\n  const usableOwners = await measureUsableOrganizationOwners({\n    organizationId: params.organizationId,\n    executionContext,\n    repositoriesRegistry: params.repositoriesRegistry,\n    errorBuilder: params.errorBuilder,\n    conferringRoles: params.conferringRoles,\n    operationIdentifier: PlatformAccessGrants_Operations.REQUEST_ACCESS,\n  });\n  return usableOwners.length > 0;\n}\n\n/**\n * Record one TENANT grant transition.\n *\n * A thin binding of {@link recordAccessGrantTransition} with this resource's scope. The emitter — the\n * post-commit deferral, the feature detection, the loss accounting — moved to\n * `access-grant-lifecycle-audit.backend.ts` on 2026-09-09 when the application-wide grant arrived,\n * because two near-copies of it would have drifted on exactly the parts that make the trail complete.\n * Nothing about the behaviour changed; see that module for the reasoning behind each half.\n */\nfunction recordGrantTransition(params: {\n  container: Container;\n  utils: { serviceOptions?: { transaction?: unknown }; logger?: { error?: (message: string, meta: unknown) => void } };\n  transition: PlatformAccessGrantLifecycleTransition;\n  grant: Record<string, unknown>;\n  decidedByUserId?: string;\n}): void {\n  recordAccessGrantTransition({ ...params, grantScope: PlatformAccessGrantScope.TENANT });\n}\n\nexport function createPlatformAccessGrantFactories(): ResourceCustomServiceImplementationFactory[] {\n  /**\n   * REQUEST — the bootstrap verb, and the only one reachable without an existing grant.\n   *\n   * Requesting is not accessing: this writes one row and touches nothing else in the tenant, which is\n   * what makes the exemption safe when the admission predicate starts requiring a grant (Step 4).\n   */\n  const requestAccessFactory = (\n    _resourcesRegistryService: ResourcesRegistryBackendService,\n    container: Container,\n  ) => {\n    const authEcFactory = container.get<AuthExecutionContextFactoryBackendService>(SAAS_SERVICE_TYPES.AuthExecutionContextFactory);\n    const organizationOwnerConferralResolver = createOrganizationOwnerConferralResolver(container);\n    return createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.PLATFORM_ACCESS_GRANTS,\n        operationIdentifier: PlatformAccessGrants_Operations.REQUEST_ACCESS,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'platform-access-grants.request-access.api',\n      // Every one of these is `.excludeFromCreate()`, so the strict request DTO drops whatever a\n      // caller sent and the prefix's value is authoritative. Declaring them makes that explicit\n      // rather than inferred — the inference has a hole for callers that reach the service tier with\n      // the key already present (MCP `callTool` forwards arguments unparsed), and on THIS resource a\n      // caller choosing their own `status` or `expiresAt` would defeat the entire mechanism.\n      authoritativeFields: ['operatorUserId', 'status', 'expiresAt', 'autoApprovalReason', 'approvedAt'],\n      transactionalCore: true,\n      transactionParticipants: { targetOrganization: CoreResourceType.ORGANIZATIONS },\n      handlers: {\n        prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n          const payload = input as { justification?: string; requestedDurationMinutes?: number };\n          // The primary-scope URL is the one target authority. The execution-context creator has\n          // already validated the mandatory `organizationId` path parameter and placed it here;\n          // reading a second body value would make callers author the security boundary twice and\n          // would preserve an unnecessary path/body mismatch state.\n          const organizationId = executionContext.organizationId;\n          const operatorUserId = executionContext.initiatorIds?.userId;\n\n          if (!organizationId || !operatorUserId) {\n            throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n              customMessageReference: ErrorCustomMessageReference.VALIDATION,\n              context: { reason: 'platform_access_grant_requires_target_and_operator' },\n            });\n          }\n\n          // Read the tenant's posture in the same unit of work as the write. Reading it outside the\n          // transaction would let a tenant that just switched Lockbox ON have a request slip through\n          // as auto-approved.\n          // Reuses the floor's own population context rather than inventing an organizations-read\n          // helper: it is already a system context authorized for the tenant-scoped reads this needs,\n          // and adding a second system-context factory for one call site is how two subtly different\n          // privileged contexts start to exist.\n          const systemEc = await createOrganizationOwnerFloorPopulationContext(authEcFactory);\n          const organization = await utils.servicesRegistry.read<Organization>(\n            CoreResourceType.ORGANIZATIONS,\n            systemEc,\n            { _id: organizationId },\n            utils.serviceOptions,\n          );\n          if (!organization) {\n            throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n              customMessageReference: ErrorCustomMessageReference.NOT_FOUND,\n              context: { reason: 'platform_access_grant_target_organization_not_found' },\n            });\n          }\n\n          const now = new Date();\n          const approvalRequired = (organization as { platformAccessApprovalRequired?: boolean }).platformAccessApprovalRequired === true;\n\n          // The circularity guard. A tenant with no administratively usable owner cannot approve\n          // anything, so requiring its approval would make its own repair impossible — the exact\n          // deadlock `organizationMembers.grantOwnership` exists to break. Measured, never assumed,\n          // and never manufacturable by the operator: stranding a tenant is what the floors refuse.\n          const canApprove = approvalRequired\n            ? await tenantHasAnApprover({\n              organizationId,\n              authEcFactory,\n              conferringRoles: organizationOwnerConferralResolver(),\n              repositoriesRegistry: utils.repositoriesRegistry,\n              errorBuilder: utils.errorBuilder,\n            })\n            : false;\n\n          const autoApprovalReason = !approvalRequired\n            ? PlatformAccessGrantAutoApprovalReason.TENANT_APPROVAL_NOT_REQUIRED\n            : (canApprove ? undefined : PlatformAccessGrantAutoApprovalReason.TENANT_CANNOT_APPROVE);\n\n          const status = autoApprovalReason\n            ? PlatformAccessGrantStatus.ACTIVE\n            : PlatformAccessGrantStatus.PENDING_APPROVAL;\n\n          return {\n            organizationId,\n            justification: payload.justification,\n            operatorUserId,\n            status,\n            expiresAt: resolvePlatformAccessGrantExpiry(payload.requestedDurationMinutes, now),\n            ...(autoApprovalReason ? { autoApprovalReason, approvedAt: now } : {}),\n          };\n        },\n        postfixCoreOperations: async (_id, createdGrant, _executionContext, _operationPath, utils) => {\n          recordGrantTransition({\n            container,\n            utils,\n            transition: PlatformAccessGrantLifecycleTransition.REQUESTED,\n            grant: (createdGrant ?? {}) as Record<string, unknown>,\n          });\n          return createdGrant;\n        },\n      },\n    });\n  };\n\n  /**\n   * The decision verbs. The shape moved to `access-grant-decision.factory.backend.ts` on 2026-09-09,\n   * when the application-wide grant needed the same four transitions plus one refusal of its own; the\n   * behaviour of every verb below is unchanged, and its reasoning lives in that module.\n   *\n   * No `additionalPrecondition` here on purpose. The application-wide `approve` refuses a\n   * self-approval; this one has no equivalent because the requester is a PLATFORM operator and the\n   * approver is a TENANT administrator gated on `CORE_ORG_ROLES.ORG_ADMIN` with no cross-tenant\n   * admission — they cannot be the same principal, and the ABSENCE of that admission is what makes it\n   * so. Adding a same-person check here would look like defence in depth and would in fact be a\n   * second, weaker statement of a control the operation config already carries absolutely.\n   */\n  const makeDecisionFactory = (\n    operationIdentifier: PlatformAccessGrants_Operations,\n    options: {\n      debugLabel: string;\n      nextStatus: PlatformAccessGrantStatus;\n      permittedFrom: readonly PlatformAccessGrantStatus[];\n      stampsApprover: boolean;\n      auditTransition: PlatformAccessGrantLifecycleTransition;\n      variantType?: ResourceOperationVariantType;\n    },\n  ): ResourceCustomServiceImplementationFactory => createAccessGrantDecisionFactory(\n    CoreResourceType.PLATFORM_ACCESS_GRANTS,\n    PlatformAccessGrantScope.TENANT,\n    operationIdentifier,\n    { ...options, transitionRefusalReason: 'platform_access_grant_transition_not_permitted_from_current_status' },\n  );\n\n  return [\n    requestAccessFactory,\n    makeDecisionFactory(PlatformAccessGrants_Operations.APPROVE, {\n      debugLabel: 'platform-access-grants.approve.api',\n      auditTransition: PlatformAccessGrantLifecycleTransition.APPROVED,\n      nextStatus: PlatformAccessGrantStatus.ACTIVE,\n      permittedFrom: [PlatformAccessGrantStatus.PENDING_APPROVAL],\n      stampsApprover: true,\n    }),\n    makeDecisionFactory(PlatformAccessGrants_Operations.DENY, {\n      debugLabel: 'platform-access-grants.deny.api',\n      auditTransition: PlatformAccessGrantLifecycleTransition.DENIED,\n      nextStatus: PlatformAccessGrantStatus.DENIED,\n      permittedFrom: [PlatformAccessGrantStatus.PENDING_APPROVAL],\n      stampsApprover: false,\n    }),\n    makeDecisionFactory(PlatformAccessGrants_Operations.REVOKE, {\n      debugLabel: 'platform-access-grants.revoke.api',\n      auditTransition: PlatformAccessGrantLifecycleTransition.REVOKED,\n      nextStatus: PlatformAccessGrantStatus.REVOKED,\n      // Both a pending request and a live elevation can be withdrawn; a terminal one cannot be\n      // re-terminated, which would rewrite the decision history.\n      permittedFrom: PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES,\n      stampsApprover: false,\n    }),\n    /**\n     * The one transition with no human actor (#413). Everything else here records a decision\n     * somebody made; this records that a window closed, so `decidedByUserId` resolves to nothing and\n     * that absence is the fact.\n     *\n     * Permitted from ACTIVE alone. A grant the tenant DENIED or REVOKED is terminal and must keep\n     * saying which — relabelling it EXPIRED would rewrite the decision history a customer audit\n     * reads, which is the opposite of why this sweep exists.\n     */\n    makeDecisionFactory(PlatformAccessGrants_Operations.EXPIRE, {\n      debugLabel: 'platform-access-grants.expire.internal',\n      auditTransition: PlatformAccessGrantLifecycleTransition.EXPIRED,\n      nextStatus: PlatformAccessGrantStatus.EXPIRED,\n      permittedFrom: [PlatformAccessGrantStatus.ACTIVE],\n      stampsApprover: false,\n      variantType: ResourceOperationVariantType.INTERNAL_CALL,\n    }),\n  ];\n}\n"]}

package/dist/esm/security/authorizations/privileged-access-review.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"privileged-access-review.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/privileged-access-review.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgE,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAEhH,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AACrK,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAGnH,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AAYrK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,6EAA6E;AAC7E,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,+BAA+B,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5D,QAAQ,CAAC,gCAAgC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7D,QAAQ,CAAC,uBAAuB,EAAE,SAAS,iCAAiC,EAAE,CAAC;IAC/E,QAAQ,CAAC,wBAAwB,EAAE,SAAS,kCAAkC,EAAE,CAAC;IACjF;;;;;;;OAOG;IACH,QAAQ,CAAC,yBAAyB,EAAE,SAAS,MAAM,EAAE,CAAC;CACvD;AAUD;;;;;;;;GAQG;AACH,wBAAsB,mCAAmC,CAAC,MAAM,EAAE;IAChE,2BAA2B,EAAE,yCAAyC,CAAC;IACvE,oBAAoB,EAAE,yCAAyC,CAAC;IAChE,YAAY,EAAE,0BAA0B,CAAC;IACzC,uGAAuG;IACvG,+BAA+B,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,sDAAsD;IACtD,gCAAgC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpD,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAqFtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2CAA2C,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAElH"}
+{"version":3,"file":"privileged-access-review.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/privileged-access-review.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgE,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAEhH,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AACrK,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAGnH,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AAYrK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,6EAA6E;AAC7E,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,+BAA+B,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5D,QAAQ,CAAC,gCAAgC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7D,QAAQ,CAAC,uBAAuB,EAAE,SAAS,iCAAiC,EAAE,CAAC;IAC/E,QAAQ,CAAC,wBAAwB,EAAE,SAAS,kCAAkC,EAAE,CAAC;IACjF;;;;;;;OAOG;IACH,QAAQ,CAAC,yBAAyB,EAAE,SAAS,MAAM,EAAE,CAAC;CACvD;AAUD;;;;;;;;GAQG;AACH,wBAAsB,mCAAmC,CAAC,MAAM,EAAE;IAChE,2BAA2B,EAAE,yCAAyC,CAAC;IACvE,oBAAoB,EAAE,yCAAyC,CAAC;IAChE,YAAY,EAAE,0BAA0B,CAAC;IACzC,uGAAuG;IACvG,+BAA+B,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,sDAAsD;IACtD,gCAAgC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpD,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAqFtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2CAA2C,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAElH"}

package/dist/esm/security/authorizations/relationship-foreign-key-filter.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-foreign-key-filter.backend.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/relationship-foreign-key-filter.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,aAAa,CAAC;QAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;KAC9B,CAAC,GAAG,IAAI,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wCAAwC;IACvD,yCAAyC,CACvC,UAAU,EAAE,GAAG,EACf,eAAe,EAAE,MAAM,EACvB,gBAAgB,EAAE,GAAG;IACrB;;;;;OAKG;IACH,iBAAiB,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GACtF,MAAM,EAAE,CAAC;IACZ,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACrD,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2CAA2C,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,EAAE;IAC1F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,2CAA2C,CAAC;IACvE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,wCAAwC,CAAC;CAChE,GAAG,IAAI,CAmCP"}
+{"version":3,"file":"relationship-foreign-key-filter.backend.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/relationship-foreign-key-filter.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,aAAa,CAAC;QAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;KAC9B,CAAC,GAAG,IAAI,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wCAAwC;IACvD,yCAAyC,CACvC,UAAU,EAAE,GAAG,EACf,eAAe,EAAE,MAAM,EACvB,gBAAgB,EAAE,GAAG;IACrB;;;;;OAKG;IACH,iBAAiB,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GACtF,MAAM,EAAE,CAAC;IACZ,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACrD,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2CAA2C,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,EAAE;IAC1F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,2CAA2C,CAAC;IACvE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,wCAAwC,CAAC;CAChE,GAAG,IAAI,CAmCP"}

package/dist/esm/security/authorizations/role-ceiling.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role-ceiling.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/role-ceiling.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0F,oBAAoB,EAA8B,MAAM,uBAAuB,CAAC;AAEjL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAC5G,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAInH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;AAE5F;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,SAAS,GAAG,qBAAqB,CAMvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,uCAAuC,CACrD,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC7C,YAAY,EAAE,0BAA0B,EACxC,qBAAqB,EAAE,qBAAqB,GAC3C,IAAI,CAiDN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI5E"}
+{"version":3,"file":"role-ceiling.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/role-ceiling.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0F,oBAAoB,EAA8B,MAAM,uBAAuB,CAAC;AAEjL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAC5G,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAInH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;AAE5F;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,SAAS,GAAG,qBAAqB,CAMvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,uCAAuC,CACrD,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC7C,YAAY,EAAE,0BAA0B,EACxC,qBAAqB,EAAE,qBAAqB,GAC3C,IAAI,CAiDN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI5E"}

package/dist/esm/security/authorizations/role-ceiling.backend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"role-ceiling.backend.utils.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/role-ceiling.backend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { CORE_APP_ROLES, ErrorCustomMessageReference, ErrorType, ExecutionContext_ExecutionType, ResourcePrimaryScope, isOrganizationWideRoleInfo } from '@wildo-ai/saas-models';\nimport type { Roles } from '@wildo-ai/saas-models';\nimport type { Container } from 'inversify';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport type { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\n\n/**\n * Expands one role into the full set of roles it effectively confers, within a given primary scope.\n *\n * This is the `inheritFrom` chain of the runtime role configuration — supply\n * `AuthorizationsBackendService.getRoleHierarchy` bound to its service instance. It is injected\n * rather than imported because the effective hierarchy is APPLICATION-CONFIGURABLE (apps register\n * custom roles at startup via `initializeRolesWithCustom`), so a statically-imported default table\n * would silently disagree with the roles the authorization layer actually enforces.\n *\n * The scope argument matters: `getRoleHierarchy` resolves against the APPLICATION role table or the\n * ORGANIZATIONS one, never both. A role string that is unknown in the passed scope expands to the\n * empty set — which is exactly the fail-closed behaviour this gate wants.\n */\nexport type RoleHierarchyResolver = (role: string, scope: ResourcePrimaryScope) => string[];\n\n/**\n * Bind a {@link RoleHierarchyResolver} to the container's live `AuthorizationsBackendService`.\n *\n * Resolution is LAZY (on first gate evaluation, then memoized) rather than at factory-construction\n * time: custom-implementation factories are built during module registration, which can run before\n * the authorization service is bound, and an eager `container.get` there would turn a role-gate into\n * a startup crash. Holding the service instance is safe across role reconfiguration —\n * `initializeRolesWithCustom` mutates the singleton's tables in place, and the hierarchy is read per\n * call, so a resolver captured at startup still sees roles registered afterwards.\n */\nexport function createRoleHierarchyResolver(container: Container): RoleHierarchyResolver {\n  let authorizationsService: AuthorizationsBackendService | undefined;\n  return (role, scope) => {\n    authorizationsService ??= container.get<AuthorizationsBackendService>(SAAS_SERVICE_TYPES.AuthorizationsService);\n    return authorizationsService.getRoleHierarchy(role as Roles, scope);\n  };\n}\n\n/**\n * @wildo_source:part:start saas.backend.authorization.role-ceiling facet:layer:backend facet:audience:app-developer\n *\n * Role-ceiling gate — a principal may only grant roles it itself holds.\n *\n * WHY THIS EXISTS. Several resources carry a caller-settable `roles` array that becomes a principal's\n * live authority. Two families:\n *\n *  - **Machine credentials** (`organizationOAuthClients` / `applicationOAuthClients` and their api-key\n *    twins): the roles written at CREATE are exactly the roles every token minted for that client/key\n *    carries at the request-auth choke point (`oauth-provider-token` → `machine-token-issuer`).\n *  - **Organization membership** (`organizationMembers.roles`, and the per-unit roles nested in\n *    `organizationUnitsMembership`): a membership row's `roles` array is read verbatim by\n *    `execution-context-creator` to build `initiatorRoles` — the member's live authority on their very\n *    next request.\n *\n * The operation-authorization layer only checks whether the CALLER may run the write at all — it never\n * compares the *requested* roles against the caller's own. Without this gate an `ORG_ADMIN` (the gate\n * for both member UPDATE and org-client CREATE) could grant `ORG_OWNER` to themselves, or mint a\n * credential carrying `APP_ADMIN_SUPER_ADMIN`. This is the missing \"you cannot grant authority you do\n * not hold\" check.\n *\n * SEMANTICS. Every requested role must lie within the caller's EFFECTIVE authority — the union of the\n * `inheritFrom` hierarchies of the roles the caller actually holds, each expanded within the scope of\n * the membership that granted it. Hierarchy-awareness is not a convenience: with the default table\n * (`ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`) an `ORG_ADMIN`'s membership row\n * holds the literal string `ORG_ADMIN` and nothing else, so a raw set-membership test would reject\n * that admin granting the DEFAULT `ORG_MEMBER` role and break the entire invite flow — while still\n * correctly rejecting a grant of `ORG_OWNER`, which is UPSTREAM of the caller and therefore outside\n * the expansion.\n *\n * Fail-closed: a caller whose roles cannot be resolved is treated as holding none, so any requested\n * role is rejected.\n *\n * TWO DELIBERATE BYPASSES:\n *  - **Platform super-admin** — a caller holding `APP_ADMIN_SUPER_ADMIN` *at APPLICATION scope* may\n *    assign any role (that role IS the top of the ceiling). This also cleanly covers the cross-tenant\n *    `admin` operation variant of the machine-credential resources, which is itself gated by\n *    `APP_ADMIN_SUPER_ADMIN` and is meant to provision clients \"for any org\" — so no separate\n *    variant-detection is needed. The scope qualifier is load-bearing: `roles` on a membership row is\n *    a free-form string (`OrgRolesSchema` admits any `z.string().min(1)`), so without it a tenant\n *    admin who wrote the literal text `APP_ADMIN_SUPER_ADMIN` into an ORGANIZATIONS-scoped membership\n *    would unlock this bypass. The authorization layer already refuses to honour that string\n *    cross-scope (`getRoleHierarchy` partitions the two role tables); this gate must not be the\n *    weaker link.\n *  - **System / internal writes** — an `INTERNALLY_INITIATED_REQUEST` execution (seeds, provisioning,\n *    `createAsSystem`) is the framework itself, not a user principal (it synthesises a super-admin\n *    system EC), and carries no human ceiling — it is trusted to assign any role.\n *\n * SCOPE OF THE COMPARISON. The caller's effective roles are unioned across every membership they\n * hold, without checking that the granting membership targets the same organization as the write.\n * That is deliberate and safe HERE because the operation-authorization layer has already confined the\n * write to a scope the caller may act in (`authorizeOrganizations` / the parent-scope filter); this\n * gate answers \"how high\", not \"where\". A future units-aware authorization axis that narrows *within*\n * an organization must revisit that assumption.\n *\n * EXTENDING. Wire this into the CREATE (and any roles-mutating UPDATE) path of ANY resource whose\n * `roles` field is caller-settable, passing the roles AS AUTHORED BY THE CALLER — not the\n * post-resolution set. Framework-injected defaults (e.g. an organization type's `defaultMemberRole`)\n * are policy-derived, not a caller request, and must not be measured against the caller's ceiling.\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — prevents a principal from granting authority it\n * does not itself hold. The denial is an access-control decision.\n *\n * @wildo_source:part:end saas.backend.authorization.role-ceiling\n */\nexport function assertRequestedRolesWithinCallerCeiling(\n  executionContext: ExecutionContext<any>,\n  requestedRoles: readonly string[] | undefined,\n  errorBuilder: ErrorBuilderBackendService,\n  roleHierarchyResolver: RoleHierarchyResolver,\n): void {\n  if (!requestedRoles || requestedRoles.length === 0) return;\n\n  // System / internal writes (seeds, provisioning, `createAsSystem`) are the framework, not a user\n  // principal — they synthesise an INTERNALLY_INITIATED_REQUEST super-admin EC and assign any role.\n  if (executionContext.executionType === ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST) {\n    return;\n  }\n\n  // Expand each held role into everything it confers, WITHIN the scope of the membership that granted\n  // it. Cross-scope contamination is impossible by construction: an ORGANIZATIONS-scoped entry is\n  // resolved against the org role table only.\n  const effectiveCallerRoles = new Set<string>();\n  let holdsPlatformSuperAdmin = false;\n  // ORGANIZATION-WIDE GRANTS ONLY. A unit-scoped role confers authority inside ONE organization\n  // unit; counting it toward the ceiling would let a member who is merely ORG_ADMIN of one team\n  // grant ORG_ADMIN across the whole tenant — the exact escalation this gate exists to stop, arriving\n  // through the gate itself.\n  for (const roleInfo of (executionContext.initiatorRoles ?? []).filter(isOrganizationWideRoleInfo)) {\n    const scope = roleInfo.relatedPrimaryScope;\n    for (const heldRole of roleInfo.roles) {\n      const conferredRoles = roleHierarchyResolver(heldRole, scope);\n      for (const conferredRole of conferredRoles) {\n        effectiveCallerRoles.add(conferredRole);\n        // The platform bypass is APPLICATION-scoped ONLY — see the doc block above.\n        if (scope === ResourcePrimaryScope.APPLICATION && conferredRole === CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN) {\n          holdsPlatformSuperAdmin = true;\n        }\n      }\n    }\n  }\n\n  // The platform / cross-tenant super-admin may assign any role (this also covers the `admin` operation\n  // variant, which is gated by exactly this role).\n  if (holdsPlatformSuperAdmin) return;\n\n  const escalatedRoles = requestedRoles.filter((role) => !effectiveCallerRoles.has(role));\n  if (escalatedRoles.length === 0) return;\n\n  // assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — deny an attempt to grant authority the caller does not\n  // itself hold. Fail-closed privilege-escalation prevention on role-conferring writes.\n  throw errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {\n    customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,\n    context: {\n      reason: 'role_ceiling_exceeded',\n      escalatedRoles,\n      callerRoles: [...effectiveCallerRoles],\n    },\n  });\n}\n\n/**\n * Collect the single authored `role` from an `ORGANIZATION_UNIT_MEMBERS` payload so it faces the\n * same ceiling as an organization-wide role grant.\n *\n * WHY THIS EXISTS. A unit assignment IS a role grant — it is the per-unit twin of\n * `OrganizationMember.roles`. It is not read by any authorization path yet (units become an\n * authorization axis in WS-C), but it is persisted and admin-editable, so an unchecked `ORG_OWNER`\n * written into an assignment is a pre-planted escalation that goes live the moment units are wired\n * into roles resolution. Gating it now removes that step.\n *\n * This replaced an array collector: until D-B5 the per-unit roles rode along inside an embedded\n * `organizationUnitsMembership` array on the members payload, so the gate had to sweep a list. As a\n * junction row there is exactly one role per payload.\n *\n * Defensive by design: this runs on UNPARSED caller input (custom-impl prefixes see the payload\n * before strict DTO validation), so a non-string role yields nothing rather than being trusted —\n * malformed input is rejected by schema validation further down the pipeline, and under-reporting\n * here can only ever deny, never grant.\n */\nexport function collectAuthoredOrganizationUnitRole(input: unknown): string[] {\n  if (input === null || typeof input !== 'object') return [];\n  const role = (input as { role?: unknown }).role;\n  return typeof role === 'string' && role.length > 0 ? [role] : [];\n}\n"]}
+{"version":3,"file":"role-ceiling.backend.utils.js","sourceRoot":"","sources":["../../../../src/security/authorizations/role-ceiling.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,SAAS,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAMjL,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAiBpF;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,SAAoB;IAC9D,IAAI,qBAA+D,CAAC;IACpE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACrB,qBAAqB,KAAK,SAAS,CAAC,GAAG,CAA+B,kBAAkB,CAAC,qBAAqB,CAAC,CAAC;QAChH,OAAO,qBAAqB,CAAC,gBAAgB,CAAC,IAAa,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,UAAU,uCAAuC,CACrD,gBAAuC,EACvC,cAA6C,EAC7C,YAAwC,EACxC,qBAA4C;IAE5C,IAAI,CAAC,cAAc,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAE3D,iGAAiG;IACjG,kGAAkG;IAClG,IAAI,gBAAgB,CAAC,aAAa,KAAK,8BAA8B,CAAC,4BAA4B,EAAE,CAAC;QACnG,OAAO;IACT,CAAC;IAED,oGAAoG;IACpG,gGAAgG;IAChG,4CAA4C;IAC5C,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/C,IAAI,uBAAuB,GAAG,KAAK,CAAC;IACpC,8FAA8F;IAC9F,8FAA8F;IAC9F,oGAAoG;IACpG,2BAA2B;IAC3B,KAAK,MAAM,QAAQ,IAAI,CAAC,gBAAgB,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAClG,MAAM,KAAK,GAAG,QAAQ,CAAC,mBAAmB,CAAC;QAC3C,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACtC,MAAM,cAAc,GAAG,qBAAqB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC9D,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;gBAC3C,oBAAoB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;gBACxC,4EAA4E;gBAC5E,IAAI,KAAK,KAAK,oBAAoB,CAAC,WAAW,IAAI,aAAa,KAAK,cAAc,CAAC,qBAAqB,EAAE,CAAC;oBACzG,uBAAuB,GAAG,IAAI,CAAC;gBACjC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,sGAAsG;IACtG,iDAAiD;IACjD,IAAI,uBAAuB;QAAE,OAAO;IAEpC,MAAM,cAAc,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAExC,2GAA2G;IAC3G,sFAAsF;IACtF,MAAM,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;QACvE,sBAAsB,EAAE,2BAA2B,CAAC,4BAA4B;QAChF,OAAO,EAAE;YACP,MAAM,EAAE,uBAAuB;YAC/B,cAAc;YACd,WAAW,EAAE,CAAC,GAAG,oBAAoB,CAAC;SACvC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mCAAmC,CAAC,KAAc;IAChE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC3D,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;IAChD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnE,CAAC","sourcesContent":["import { CORE_APP_ROLES, ErrorCustomMessageReference, ErrorType, ExecutionContext_ExecutionType, ResourcePrimaryScope, isOrganizationWideRoleInfo } from '@wildo-ai/saas-models';\nimport type { Roles } from '@wildo-ai/saas-models';\nimport type { Container } from 'inversify';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport type { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\n\n/**\n * Expands one role into the full set of roles it effectively confers, within a given primary scope.\n *\n * This is the `inheritFrom` chain of the runtime role configuration — supply\n * `AuthorizationsBackendService.getRoleHierarchy` bound to its service instance. It is injected\n * rather than imported because the effective hierarchy is APPLICATION-CONFIGURABLE (apps register\n * custom roles at startup via `initializeRolesWithCustom`), so a statically-imported default table\n * would silently disagree with the roles the authorization layer actually enforces.\n *\n * The scope argument matters: `getRoleHierarchy` resolves against the APPLICATION role table or the\n * ORGANIZATIONS one, never both. A role string that is unknown in the passed scope expands to the\n * empty set — which is exactly the fail-closed behaviour this gate wants.\n */\nexport type RoleHierarchyResolver = (role: string, scope: ResourcePrimaryScope) => string[];\n\n/**\n * Bind a {@link RoleHierarchyResolver} to the container's live `AuthorizationsBackendService`.\n *\n * Resolution is LAZY (on first gate evaluation, then memoized) rather than at factory-construction\n * time: custom-implementation factories are built during module registration, which can run before\n * the authorization service is bound, and an eager `container.get` there would turn a role-gate into\n * a startup crash. Holding the service instance is safe across role reconfiguration —\n * `initializeRolesWithCustom` mutates the singleton's tables in place, and the hierarchy is read per\n * call, so a resolver captured at startup still sees roles registered afterwards.\n */\nexport function createRoleHierarchyResolver(container: Container): RoleHierarchyResolver {\n  let authorizationsService: AuthorizationsBackendService | undefined;\n  return (role, scope) => {\n    authorizationsService ??= container.get<AuthorizationsBackendService>(SAAS_SERVICE_TYPES.AuthorizationsService);\n    return authorizationsService.getRoleHierarchy(role as Roles, scope);\n  };\n}\n\n/**\n * @wildo_source:part:start saas.backend.authorization.role-ceiling facet:layer:backend facet:audience:app-developer\n *\n * Role-ceiling gate — a principal may only grant roles it itself holds.\n *\n * WHY THIS EXISTS. Several resources carry a caller-settable `roles` array that becomes a principal's\n * live authority. Two families:\n *\n *  - **Machine credentials** (`organizationOAuthClients` / `applicationOAuthClients` and their api-key\n *    twins): the roles written at CREATE are exactly the roles every token minted for that client/key\n *    carries at the request-auth choke point (`oauth-provider-token` → `machine-token-issuer`).\n *  - **Organization membership** (`organizationMembers.roles`, and the per-unit roles nested in\n *    `organizationUnitsMembership`): a membership row's `roles` array is read verbatim by\n *    `execution-context-creator` to build `initiatorRoles` — the member's live authority on their very\n *    next request.\n *\n * The operation-authorization layer only checks whether the CALLER may run the write at all — it never\n * compares the *requested* roles against the caller's own. Without this gate an `ORG_ADMIN` (the gate\n * for both member UPDATE and org-client CREATE) could grant `ORG_OWNER` to themselves, or mint a\n * credential carrying `APP_ADMIN_SUPER_ADMIN`. This is the missing \"you cannot grant authority you do\n * not hold\" check.\n *\n * SEMANTICS. Every requested role must lie within the caller's EFFECTIVE authority — the union of the\n * `inheritFrom` hierarchies of the roles the caller actually holds, each expanded within the scope of\n * the membership that granted it. Hierarchy-awareness is not a convenience: with the default table\n * (`ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`) an `ORG_ADMIN`'s membership row\n * holds the literal string `ORG_ADMIN` and nothing else, so a raw set-membership test would reject\n * that admin granting the DEFAULT `ORG_MEMBER` role and break the entire invite flow — while still\n * correctly rejecting a grant of `ORG_OWNER`, which is UPSTREAM of the caller and therefore outside\n * the expansion.\n *\n * Fail-closed: a caller whose roles cannot be resolved is treated as holding none, so any requested\n * role is rejected.\n *\n * TWO DELIBERATE BYPASSES:\n *  - **Platform super-admin** — a caller holding `APP_ADMIN_SUPER_ADMIN` *at APPLICATION scope* may\n *    assign any role (that role IS the top of the ceiling). This also cleanly covers the cross-tenant\n *    `admin` operation variant of the machine-credential resources, which is itself gated by\n *    `APP_ADMIN_SUPER_ADMIN` and is meant to provision clients \"for any org\" — so no separate\n *    variant-detection is needed. The scope qualifier is load-bearing: `roles` on a membership row is\n *    a free-form string (`OrgRolesSchema` admits any `z.string().min(1)`), so without it a tenant\n *    admin who wrote the literal text `APP_ADMIN_SUPER_ADMIN` into an ORGANIZATIONS-scoped membership\n *    would unlock this bypass. The authorization layer already refuses to honour that string\n *    cross-scope (`getRoleHierarchy` partitions the two role tables); this gate must not be the\n *    weaker link.\n *  - **System / internal writes** — an `INTERNALLY_INITIATED_REQUEST` execution (seeds, provisioning,\n *    `createAsSystem`) is the framework itself, not a user principal (it synthesises a super-admin\n *    system EC), and carries no human ceiling — it is trusted to assign any role.\n *\n * SCOPE OF THE COMPARISON. The caller's effective roles are unioned across every membership they\n * hold, without checking that the granting membership targets the same organization as the write.\n * That is deliberate and safe HERE because the operation-authorization layer has already confined the\n * write to a scope the caller may act in (`authorizeOrganizations` / the parent-scope filter); this\n * gate answers \"how high\", not \"where\". A future units-aware authorization axis that narrows *within*\n * an organization must revisit that assumption.\n *\n * EXTENDING. Wire this into the CREATE (and any roles-mutating UPDATE) path of ANY resource whose\n * `roles` field is caller-settable, passing the roles AS AUTHORED BY THE CALLER — not the\n * post-resolution set. Framework-injected defaults (e.g. an organization type's `defaultMemberRole`)\n * are policy-derived, not a caller request, and must not be measured against the caller's ceiling.\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — prevents a principal from granting authority it\n * does not itself hold. The denial is an access-control decision.\n *\n * @wildo_source:part:end saas.backend.authorization.role-ceiling\n */\nexport function assertRequestedRolesWithinCallerCeiling(\n  executionContext: ExecutionContext<any>,\n  requestedRoles: readonly string[] | undefined,\n  errorBuilder: ErrorBuilderBackendService,\n  roleHierarchyResolver: RoleHierarchyResolver,\n): void {\n  if (!requestedRoles || requestedRoles.length === 0) return;\n\n  // System / internal writes (seeds, provisioning, `createAsSystem`) are the framework, not a user\n  // principal — they synthesise an INTERNALLY_INITIATED_REQUEST super-admin EC and assign any role.\n  if (executionContext.executionType === ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST) {\n    return;\n  }\n\n  // Expand each held role into everything it confers, WITHIN the scope of the membership that granted\n  // it. Cross-scope contamination is impossible by construction: an ORGANIZATIONS-scoped entry is\n  // resolved against the org role table only.\n  const effectiveCallerRoles = new Set<string>();\n  let holdsPlatformSuperAdmin = false;\n  // ORGANIZATION-WIDE GRANTS ONLY. A unit-scoped role confers authority inside ONE organization\n  // unit; counting it toward the ceiling would let a member who is merely ORG_ADMIN of one team\n  // grant ORG_ADMIN across the whole tenant — the exact escalation this gate exists to stop, arriving\n  // through the gate itself.\n  for (const roleInfo of (executionContext.initiatorRoles ?? []).filter(isOrganizationWideRoleInfo)) {\n    const scope = roleInfo.relatedPrimaryScope;\n    for (const heldRole of roleInfo.roles) {\n      const conferredRoles = roleHierarchyResolver(heldRole, scope);\n      for (const conferredRole of conferredRoles) {\n        effectiveCallerRoles.add(conferredRole);\n        // The platform bypass is APPLICATION-scoped ONLY — see the doc block above.\n        if (scope === ResourcePrimaryScope.APPLICATION && conferredRole === CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN) {\n          holdsPlatformSuperAdmin = true;\n        }\n      }\n    }\n  }\n\n  // The platform / cross-tenant super-admin may assign any role (this also covers the `admin` operation\n  // variant, which is gated by exactly this role).\n  if (holdsPlatformSuperAdmin) return;\n\n  const escalatedRoles = requestedRoles.filter((role) => !effectiveCallerRoles.has(role));\n  if (escalatedRoles.length === 0) return;\n\n  // assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — deny an attempt to grant authority the caller does not\n  // itself hold. Fail-closed privilege-escalation prevention on role-conferring writes.\n  throw errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {\n    customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,\n    context: {\n      reason: 'role_ceiling_exceeded',\n      escalatedRoles,\n      callerRoles: [...effectiveCallerRoles],\n    },\n  });\n}\n\n/**\n * Collect the single authored `role` from an `ORGANIZATION_UNIT_MEMBERS` payload so it faces the\n * same ceiling as an organization-wide role grant.\n *\n * WHY THIS EXISTS. A unit assignment IS a role grant — it is the per-unit twin of\n * `OrganizationMember.roles`. It is not read by any authorization path yet (units become an\n * authorization axis in WS-C), but it is persisted and admin-editable, so an unchecked `ORG_OWNER`\n * written into an assignment is a pre-planted escalation that goes live the moment units are wired\n * into roles resolution. Gating it now removes that step.\n *\n * This replaced an array collector: until D-B5 the per-unit roles rode along inside an embedded\n * `organizationUnitsMembership` array on the members payload, so the gate had to sweep a list. As a\n * junction row there is exactly one role per payload.\n *\n * Defensive by design: this runs on UNPARSED caller input (custom-impl prefixes see the payload\n * before strict DTO validation), so a non-string role yields nothing rather than being trusted —\n * malformed input is rejected by schema validation further down the pipeline, and under-reporting\n * here can only ever deny, never grant.\n */\nexport function collectAuthoredOrganizationUnitRole(input: unknown): string[] {\n  if (input === null || typeof input !== 'object') return [];\n  const role = (input as { role?: unknown }).role;\n  return typeof role === 'string' && role.length > 0 ? [role] : [];\n}\n"]}

package/dist/esm/security/authorizations/role-conferral.backend.utils.d.ts

@@ -90,4 +90,44 @@ export declare function resolveRolesConferringAnchor(params: {
     readonly declaredRoleKeys: readonly string[];
     readonly roleHierarchyResolver: (roleKey: string, scope: ResourcePrimaryScope) => string[];
 }): string[];
+/**
+ * Does holding `heldRoleKey` in `scope` satisfy a gate that requires `requiredRoleKey`?
+ *
+ * ## The one place the scope partition is consulted
+ *
+ * This is the ATOM. Everything this module's header argues about the vocabulary lands here: the role
+ * key is an open string, the SCOPE partition is what is closed, and the safety comes from RESOLUTION
+ * rather than from the field's type — a key unknown in `scope` expands to the EMPTY chain and
+ * therefore confers nothing, which is what makes an application-scope string written into an
+ * organisation-scoped membership row harmless. Every copy of these two lines is another place that
+ * argument can quietly stop being true, and the only way to notice would be a security test nobody
+ * wrote.
+ *
+ * ## Two names for one parameter, deliberately
+ *
+ * A FLOOR calls the target an ANCHOR — it is measuring the population that reaches an authority. A
+ * GATE calls it the REQUIRED ROLE — it is deciding one caller. Same question of the same table, so
+ * the parameter is named neutrally here rather than picked from one caller's vocabulary.
+ *
+ * ## What this does NOT do, and must not grow into
+ *
+ * It answers about ONE held key. The quantifier belongs to the caller, and the callers genuinely
+ * differ: `resolveRolesConferringAnchor` maps it over the declared role TABLE to produce a SET, so a
+ * floor can measure a protected population; an admission maps it over the roles the CALLER holds to
+ * produce a BOOLEAN. Those are two different questions and collapsing them into one helper that
+ * "does both" is the convenience-over-semantics failure `.claude/rules/design-philosophy.md` refuses.
+ * The distinction is kept; only the shared atom is named — which is what that rule asks for when it
+ * says to add helpers for controlled merging instead of collapsing a distinction.
+ *
+ * @param heldRoleKey a role key a principal holds, or a key declared in the role table.
+ * @param requiredRoleKey the authority being tested for — a floor's anchor, or a gate's required role.
+ * @param scope which role table `heldRoleKey` is to be read against. Passing the wrong one resolves
+ *   to the empty chain and answers `false`, which is the fail-CLOSED direction for both callers.
+ */
+export declare function roleConfersAuthority(params: {
+    readonly heldRoleKey: string;
+    readonly requiredRoleKey: string;
+    readonly scope: ResourcePrimaryScope;
+    readonly roleHierarchyResolver: (roleKey: string, scope: ResourcePrimaryScope) => string[];
+}): boolean;
 //# sourceMappingURL=role-conferral.backend.utils.d.ts.map

package/dist/esm/security/authorizations/role-conferral.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role-conferral.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/role-conferral.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,qBAAqB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;CAC5F,GAAG,MAAM,EAAE,CAUX"}
+{"version":3,"file":"role-conferral.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/role-conferral.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,qBAAqB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;CAC5F,GAAG,MAAM,EAAE,CAeX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,qBAAqB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;CAC5F,GAAG,OAAO,CAEV"}

package/dist/esm/security/authorizations/role-conferral.backend.utils.js

@@ -86,10 +86,52 @@
 export function resolveRolesConferringAnchor(params) {
     const conferringRoles = new Set([params.anchorRole]);
     for (const roleKey of params.declaredRoleKeys) {
-        if (params.roleHierarchyResolver(roleKey, params.scope).includes(params.anchorRole)) {
+        if (roleConfersAuthority({
+            heldRoleKey: roleKey,
+            requiredRoleKey: params.anchorRole,
+            scope: params.scope,
+            roleHierarchyResolver: params.roleHierarchyResolver,
+        })) {
             conferringRoles.add(roleKey);
         }
     }
     return [...conferringRoles];
 }
+/**
+ * Does holding `heldRoleKey` in `scope` satisfy a gate that requires `requiredRoleKey`?
+ *
+ * ## The one place the scope partition is consulted
+ *
+ * This is the ATOM. Everything this module's header argues about the vocabulary lands here: the role
+ * key is an open string, the SCOPE partition is what is closed, and the safety comes from RESOLUTION
+ * rather than from the field's type — a key unknown in `scope` expands to the EMPTY chain and
+ * therefore confers nothing, which is what makes an application-scope string written into an
+ * organisation-scoped membership row harmless. Every copy of these two lines is another place that
+ * argument can quietly stop being true, and the only way to notice would be a security test nobody
+ * wrote.
+ *
+ * ## Two names for one parameter, deliberately
+ *
+ * A FLOOR calls the target an ANCHOR — it is measuring the population that reaches an authority. A
+ * GATE calls it the REQUIRED ROLE — it is deciding one caller. Same question of the same table, so
+ * the parameter is named neutrally here rather than picked from one caller's vocabulary.
+ *
+ * ## What this does NOT do, and must not grow into
+ *
+ * It answers about ONE held key. The quantifier belongs to the caller, and the callers genuinely
+ * differ: `resolveRolesConferringAnchor` maps it over the declared role TABLE to produce a SET, so a
+ * floor can measure a protected population; an admission maps it over the roles the CALLER holds to
+ * produce a BOOLEAN. Those are two different questions and collapsing them into one helper that
+ * "does both" is the convenience-over-semantics failure `.claude/rules/design-philosophy.md` refuses.
+ * The distinction is kept; only the shared atom is named — which is what that rule asks for when it
+ * says to add helpers for controlled merging instead of collapsing a distinction.
+ *
+ * @param heldRoleKey a role key a principal holds, or a key declared in the role table.
+ * @param requiredRoleKey the authority being tested for — a floor's anchor, or a gate's required role.
+ * @param scope which role table `heldRoleKey` is to be read against. Passing the wrong one resolves
+ *   to the empty chain and answers `false`, which is the fail-CLOSED direction for both callers.
+ */
+export function roleConfersAuthority(params) {
+    return params.roleHierarchyResolver(params.heldRoleKey, params.scope).includes(params.requiredRoleKey);
+}
 //# sourceMappingURL=role-conferral.backend.utils.js.map