@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/users/users.shared.resources-config.schemas.js

@@ -13,7 +13,10 @@ import { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resourc
 import { ResourceOperationVariantType } from '../resources/resources.shared.schemas.js';
 import { CoreUserNotificationTarget, CoreUserNotificationChannel } from '../notifications/notifications.shared.schemas.js';
 import { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory.js';
+import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
+import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas.js';
 import { CORE_APP_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+import { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas.js';
 // Sort and filter fields for user management
 const USERS_SORT_FIELDS = ['createdAt', 'updatedAt', 'joinedAt', 'email'];
 // App users get basic filter fields
@@ -31,6 +34,105 @@ const USERS_ADMIN_FILTER_FIELDS = {
 // App Admin gets additional sorting capabilities
 const USERS_ADMIN_SORT_FIELDS = [...USERS_SORT_FIELDS, 'status'];
 // Custom operations enum for user management
+//
+// Invitation is intentionally absent. Organization invitations are created by
+// the organization-members lifecycle, where the pending membership, invitee
+// identity, token and email are produced together. A previous `send_invitation`
+// users operation declared an invitation-receipt DTO but registered no backend
+// implementation capable of producing it. Reintroduce an application-wide
+// invitation operation only with a real lifecycle owner and handler; an
+// API_CALL declaration by itself is not an implementation.
+//
+// IMPERSONATION IS NOT A TOKEN MINT — IT IS AN IDENTITY SUBSTRATE THE FRAMEWORK DOES NOT HAVE.
+// `IMPERSONATE` was declared here as an `APP_ADMIN_SUPER_ADMIN`-gated `riskLevel: CRITICAL`
+// operation taking `{ reason, durationMinutes, auditLog }` and promising a
+// `{ impersonationToken, expiresAt, auditId }` response, and was removed on 2026-08-01: it was
+// ROUTED but never implemented. With `resourceOperationLike: READ` the generic core path simply
+// returned the target's user row, so the most dangerous verb in the catalogue answered
+// **HTTP 200** — an operator is told an impersonation session exists when none does.
+//
+// Do NOT re-declare it as a plain token mint. A minted session JWT is today byte-for-byte
+// indistinguishable from a genuine one: the payload is `{…, sub: userId, aud: 'AUTH_TOKEN' }`
+// with NO actor claim, and `ExecutionContext` has no "acting as" dimension. Every audit event
+// raised during such a session would be attributed to the impersonated USER rather than the
+// administrator — the framework would manufacture false attribution in exactly the records an
+// auditor relies on. That is strictly worse than having no impersonation at all.
+//
+// Re-declaring requires, as one workstream:
+//   1. an actor claim on the session JWT (RFC 8693 `act`-style: `sub` = target, actor = admin),
+//      minted through a dedicated path — never by reusing the ordinary login issuer;
+//   2. `ExecutionContext` propagation of that actor, so it reaches every downstream consumer;
+//   3. actor-attributed audit events — a new `CoreAuditableEventType` pair for session start/end
+//      plus actor stamping on every event raised while impersonating;
+//   4. an explicit revocation path (revoking the impersonation must not log the real user out);
+//   5. a server-side hard duration cap from configuration — NOT a caller-supplied
+//      `durationMinutes`, and NOT a caller-supplied `auditLog` flag: an audit trail the actor can
+//      switch off is not an audit trail, which is why that field is not preserved here;
+//   6. notification to the impersonated user, not only to administrators;
+//   7. a forbidden-while-impersonating operation set (credential change, account deletion,
+//      API-key/token minting, and any further impersonation);
+//   8. an unmistakable frontend banner for the whole session.
+//
+// assurance-control: WILDO.IDENTITY.SESSION_ASSURANCE · TODO(assurance-control) — privileged access
+// under another identity must be authorized, time-boxed, and attributable to the human actor.
+// See `.claude/plans/routed-unimplemented-operations-fail-closed.md`.
+//
+// ACCOUNT MERGE IS A MULTI-RESOURCE CAPABILITY — NOT AN UPDATE ON `users`.
+// `MERGE_ACCOUNTS` was declared here as an `APP_ADMIN_SUPER_ADMIN`-gated `riskLevel: CRITICAL`
+// operation taking `{ targetUserId, keepPrimaryUser, mergeProfile, mergePreferences,
+// mergeOrganizations, reason }` and promising a `{ mergedUser, removedUserId, mergedDataSummary }`
+// response, and was removed on 2026-08-01: it was ROUTED but never implemented. Not one request
+// field is a persisted `users` field, so the controller and repository strict parses left an empty
+// `$set` — nothing merged, nothing was removed, and the declared response could never be produced.
+//
+// It was removed rather than implemented because nothing asks for it AND the identity model
+// prevents the duplicate class it names:
+//   - `UserSchema.email` is the STRICT unique identity anchor — "there is never more than one
+//     `User` per email". All five provisioning paths (self-registration, org-admin invite, SSO JIT,
+//     SCIM, anonymous transposition) find-or-create by the normalized value; `.toLowerCase()`
+//     closes the casing fork and `.excludeFromUpdate()` keeps the anchor immutable.
+//   - The multi-provider case — one human, several IdPs — is already first-class via
+//     `USER_IDENTITY_LINKS` (many links per user, compound-unique per tenant connection).
+//     There is nothing to merge.
+//   - No duplicate-detection surface exists anywhere, so nothing could ever supply `targetUserId`.
+//     The verb had no consumer AND no producer.
+//
+// Do NOT re-declare it as an `UPDATE` on `users`. A merge is a transactional identity move across
+// every resource holding a `userId` FK (~21 engine schema/resource-config files declare one, plus
+// every app-defined resource the engine cannot enumerate), and the framework has no such primitive
+// today: the closest prior art, `AnonymousSessionBackendService.transposeOwnership()`, loops
+// resource types accumulating `failedTypes[]` and reports partial failure instead of rolling back.
+// Note also that `ResourceTranspositionPolicy.MERGE` is declared vocabulary that no resource
+// selects and that warns "not yet implemented — falling back to ADD" — the same problem, in its
+// easier form (a receiving identity with no competing state), was already left undone
+// (tracked as RESCONFIG-10 in `.claude/plans/DEFERRED.md`).
+//
+// Re-declaring requires, as one workstream:
+//   1. a duplicate-detection surface that produces merge candidates — without it the verb has no
+//      caller, which is how the removed declaration ended up unreachable;
+//   2. a cross-resource transaction via `resolveResourceOperationTransactionPersistenceContract`
+//      (`transactionalCore` + named `transactionParticipants`), NOT a per-resource loop that can
+//      half-apply and leave two partially-merged identities;
+//   3. an FK-graph walk reusing the subject-erasure traversal in `compliance/` rather than a
+//      re-derived inventory that silently misses app-defined resources;
+//   4. explicit conflict resolution for the 1:1 compositions (`USER_PROFILES`, `USER_PREFERENCES`
+//      are `.isUnique()` per user) and for two memberships in the same organization — the removed
+//      `mergeProfile` / `mergePreferences` / `mergeOrganizations` booleans named the axes but
+//      decided nothing;
+//   5. a settled, WRITTEN-DOWN answer for the losing user's audit history. It must NOT be silently
+//      rewritten: `auditable-events.shared.schema.ts` is the densest `userId` holder in the engine
+//      (32 occurrences), and re-pointing those rows would forge the record an auditor relies on;
+//   6. a dedicated auditable event for the merge itself — the removed operation emitted nothing at
+//      all. (Operation-level auditing now exists via risk-tiered `RESOURCE_OPERATION_PERFORMED`
+//      emission, so a reinstated merge verb would inherit a row from its declared risk level; it
+//      would still need its own event to name the two identities being consolidated.);
+//   7. a decision on the erasure interaction: a merged-away identity that was subject to retention
+//      must not resurrect scrubbed personal data through the surviving row.
+//
+// assurance-control: WILDO.IDENTITY.LIFECYCLE · TODO(assurance-control) — consolidating two
+// identities is a privileged identity-lifecycle change and must be authorized, attributable, and
+// non-destructive to the audit trail.
+// See `.claude/plans/routed-unimplemented-operations-fail-closed.md`.
 export var Users_Operations;
 (function (Users_Operations) {
     Users_Operations["ASSIGN_ROLES"] = "assign_roles";
@@ -38,10 +140,6 @@ export var Users_Operations;
     Users_Operations["SUSPEND_USER"] = "suspend_user";
     Users_Operations["UNSUSPEND_USER"] = "unsuspend_user";
     Users_Operations["FORCE_PASSWORD_RESET"] = "force_password_reset";
-    Users_Operations["IMPERSONATE"] = "impersonate";
-    Users_Operations["MERGE_ACCOUNTS"] = "merge_accounts";
-    Users_Operations["EXPORT_USER_DATA"] = "export_user_data";
-    Users_Operations["SEND_INVITATION"] = "send_invitation";
 })(Users_Operations || (Users_Operations = {}));
 /*
 Users Resource Configuration Factory
@@ -52,12 +150,102 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
     resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],
     resourceRelationships: resourcesRelationships,
     isSystemResource: true, // Users are app-scoped
+    /**
+     * `/users/{userId}` names the TARGET of an administrative action, never the caller.
+     *
+     * This resource's `resourceFieldIdentifier` is `userId` — the same key the W3.6 identity-coherence
+     * guard compares against the JWT subject. Without this declaration that guard read every
+     * `/users/{targetId}` request as "the caller claims to be targetId" and refused it with
+     * `403 authorization_user_id_mismatch`, which made the ENTIRE administrative surface unreachable
+     * cross-user: `assign_roles`, `revoke_roles`, `suspend_user`, `unsuspend_user`,
+     * `force_password_reset`, the admin READ and the core UPDATE/DELETE. Every one of those is
+     * documented in the resource specification as acting on "another user's record" and is surfaced in
+     * the admin UI as a per-row action, so the framework contradicted itself.
+     *
+     * ⚠️ The SIBLING resource must keep the default. `USER_SELF` is a second configuration over the
+     * SAME collection and shares this exact field identifier ("Same as USERS but different context"),
+     * but there the segment genuinely names the caller — so it stays `true` and its horizontal-IDOR
+     * refusal keeps holding. The two are indistinguishable structurally, which is precisely why this
+     * is declared rather than inferred.
+     *
+     * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an administrative action on another principal
+     * is authorized by the caller's ROLE, not by the caller and the subject being the same person.
+     */
+    primaryKeyIdentifiesInitiator: false,
+    // create: org-admin invite eagerly provisions a `User{status: PENDING_INVITATION}`
+    // in-process (the invitee has no account yet). The API_CALL CREATE variant is
+    // APP_ADMIN_SUPER_ADMIN-gated AND manually omits `status`/`appRoles` from its DTO, so
+    // a plain create could neither be issued by the org admin nor persist the non-default
+    // status. Opt CREATE into the trusted `createAsSystem` path (fail-closed elsewhere):
+    // the synthesized super-admin context satisfies the ACL and `preserveServerInjectedFields`
+    // re-attaches `status` past the DTO strip. See organization-member-custom-implementation.
+    //
+    // read: the INBOUND_CONTACTS anonymous-CREATE lead-triage prefix
+    // (`inbound-contact-custom-implementation`) must look up a user by email from an
+    // ANONYMOUS context that cannot read USERS. It routes that request-triggered bypass
+    // through the sanctioned `readAsSystem` (fail-closed + `SYSTEM_CONTEXT_READ` audit)
+    // rather than a hand-built super-admin EC. The caller enforces its own boundary: it
+    // consumes ONLY `.status` and returns ONLY a `.isBackendOnly()` enum, so the full
+    // super-admin row never reaches the anonymous submitter (no enumeration oracle).
+    systemAccessPolicy: {
+        exportSubject: ResourceSystemAccessMode.ALLOWED,
+        create: ResourceSystemAccessMode.ALLOWED,
+        read: ResourceSystemAccessMode.ALLOWED,
+        /**
+         * Trusted server-side ACTIVATION / DEACTIVATION of a user's lifecycle `status`.
+         *
+         * `status` is `.excludeFromUpdate()`, so the client-facing UPDATE contract cannot carry it and
+         * the lifecycle verbs (`suspend_user` / `unsuspend_user`) own the administrative transitions.
+         * But four trusted flows legitimately move `status` WITHOUT a caller — email verification
+         * (`PENDING_VERIFICATION → ACTIVE`), SCIM re-activation, and SCIM/IdP deprovisioning
+         * (`→ INACTIVE`) — and none of them is a lifecycle verb: they are consequences of an
+         * out-of-band fact (a confirmed email, a directory row disappearing), not an operator decision
+         * with a reason and a state machine.
+         *
+         * `updateAsSystem` is the door for exactly that shape, and it re-attaches the excluded field
+         * past the strict request-DTO parse. Without this grant those writes are silently stripped and
+         * users simply never activate — no error, no signal.
+         */
+        update: ResourceSystemAccessMode.ALLOWED,
+        // `updateMany` + `seeRetained` are NOT authored here — `retentionPolicy` derives both, and
+        // authoring either as FORBIDDEN is a config error. Leave them to the factory.
+    },
+    /**
+     * Subject erasure scrubs-and-RETAINS the user row instead of deleting it: the retained financial
+     * records (invoices, usage) keep a resolvable foreign key, now pointing at an anonymized subject.
+     * `RETAIN_AND_IMPERSONALIZE` because this row DOES hold personal data of its own — `email` — which
+     * the scrub masks to `ERASED_USER_EMAIL`. A retained row is hidden from every normal read and
+     * frozen; only the audited `seeRetained` path can reach it.
+     *
+     * ⚠️ `USER_SELF` declares the SAME policy on purpose. It is a second resource config over the SAME
+     * `users` collection (see `getCollectionNameForResource` in the zod→mongoose convertor: separate
+     * models, one collection). Retention governance is per-config, so opting in only here would leave
+     * an erased row readable AND updatable through the USER_SELF door, and would put a PLAIN unique
+     * index on `email` alongside this one's retention-scoped index — which the second erasure would
+     * then collide with (E11000) and abort. The two configs must be changed together.
+     */
+    retentionPolicy: {
+        mode: ErasureRetentionMode.RETAIN_AND_IMPERSONALIZE,
+    },
+    /**
+     * The subject IS this row: erasing user `X` ends the session of user `X`. Declaring it makes that
+     * revocation EXPLICIT — until now it happened only as a side effect of the retention row-hide (the
+     * auth fronts re-read the user, find the row hidden, and 401) plus the scrub bumping
+     * `authorizationVersion`. Neither is a written revocation, so the guarantee rested entirely on two
+     * unrelated mechanisms continuing to behave that way.
+     */
+    dataSubjectPolicy: { kind: ResourceDataSubjectKind.SELF_PRINCIPAL },
+    /**
+     * Subject-export disclosure. The operator-facing export subject.
+     */
+    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.SUBJECT_PROVIDED },
     coreOperations: [
         CoreResourceOperation.READ,
         CoreResourceOperation.LIST,
         CoreResourceOperation.SEARCH,
         CoreResourceOperation.CREATE,
         CoreResourceOperation.UPDATE,
+        CoreResourceOperation.UPDATE_MANY,
         CoreResourceOperation.DELETE,
     ],
     customOperation: Users_Operations,
@@ -67,8 +255,20 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_USER], // v1: app users can view other users
+                    roles: [CORE_APP_ROLES.APP_USER],
                     riskLevel: ResourceOperationRiskLevel.LOW,
+                    // ⚠️ DELIBERATELY NOT `admitsCrossSubjectUserAdministration`. This variant is gated
+                    // `APP_USER`, so admitting cross-subject addressing here would let ANY authenticated user
+                    // read ANY other user's row — `email`, `appRoles`, `status` — for every application built
+                    // on the framework. Reading another user is the `admin` variant's job, directly below.
+                    //
+                    // The pre-existing comment on this line read "v1: app users can view other users", which
+                    // the USER_SELF-scope authorization has never permitted (`authorizeUserSelf` requires the
+                    // addressed row to BE the caller). The claim was aspirational, not behaviour — removed
+                    // rather than acted on, because acting on it is a privacy decision for the product, not a
+                    // side effect of fixing the administrative surface. If app users SHOULD be able to view
+                    // each other, that wants its own decision, its own DTO narrowing (this variant returns the
+                    // full row today) and its own probes.
                 },
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
@@ -76,18 +276,31 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     variantKey: "admin",
                     roles: [CORE_APP_ROLES.APP_ADMIN_VIEWER],
                     riskLevel: ResourceOperationRiskLevel.LOW,
+                    // THE administrative read. Gated `APP_ADMIN_VIEWER`, and the surface the admin UI's user
+                    // list is built on — so it must be able to address someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                 }
             ]
         },
         [CoreResourceOperation.LIST]: {
             variants: [
                 {
+                    // Framework-internal LIST only — INTERNAL_CALL registers NO HTTP route, so
+                    // this is never reachable by an app user (or anyone) over HTTP. It exists for
+                    // internal enumeration (e.g. enrichment / labelling), invoked with a system
+                    // execution context that carries APP_ADMIN_SUPER_ADMIN. `roles: []` is inert
+                    // here precisely because it is not URL-bearing and role-gating is bypassed for
+                    // internal execution — it is NOT "any app user can list users" (an empty roles
+                    // array on a URL-bearing variant would be fail-closed → 403). App users do not
+                    // get a global list-all; they READ a user (APP_USER) and enumerate via the
+                    // org-scoped SEARCH people-picker below.
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
-                    roles: [], // v1: app users can list users
+                    roles: [],
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 },
                 {
+                    // The ONLY HTTP-exposed LIST — admin-gated global user listing.
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: false,
                     variantKey: "admin",
@@ -105,7 +318,26 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     roles: [CORE_APP_ROLES.APP_ADMIN_VIEWER],
                     riskLevel: ResourceOperationRiskLevel.LOW,
                     isSearchable: true,
-                    searchableFields: ['email', 'firstName', 'lastName', 'username'],
+                    // `email` is the only human-searchable field ON the user row. First/last
+                    // name and display name live on `USER_PROFILES` (1:1, keyed by `userId`)
+                    // and are MUTABLE there, so they are searched RELATIONALLY rather than
+                    // denormalized: the framework searches `USER_PROFILES` (by its own
+                    // searchable fields — firstName/lastName/displayName) and intersects the
+                    // matching `userId`s with this resource's `_id`. (`username` was a phantom
+                    // field — it exists on no user collection — and has been removed.) This
+                    // powers the org-scoped "people picker" (e.g. a `createdByUserId` filter):
+                    // the junction scope filter keeps results within the caller's org.
+                    // See SearchableRelationDescriptor in resources-config.shared.schemas.ts.
+                    searchableFields: [
+                        'email',
+                        {
+                            localField: '_id',
+                            relatedResource: CoreResourceType.USER_PROFILES,
+                            relatedJoinField: 'userId',
+                            // fields omitted → defaults to USER_PROFILES' own searchableFields
+                            // (firstName, lastName, displayName).
+                        },
+                    ],
                     searchableOptions: { caseSensitive: false, fullMatchOnly: false },
                     filterFields: USERS_ADMIN_FILTER_FIELDS,
                     sortFields: USERS_ADMIN_SORT_FIELDS,
@@ -120,8 +352,15 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only operation
                     riskLevel: ResourceOperationRiskLevel.HIGH,
-                    // DTOs auto-derived from decorators (excludeFromCreate on _id, createdAt, updatedAt)
-                    // status and appRoles still manually excluded for this variant
+                    // DTOs auto-derived from decorators (excludeFromCreate on _id, createdAt, updatedAt).
+                    //
+                    // ⚠️ `status` and `appRoles` ARE part of this create contract. An earlier comment here
+                    // claimed they were "manually excluded"; they never were — neither field carries
+                    // `.excludeFromCreate()` and this variant declares no narrowing `requestDto`, so both are
+                    // accepted (confirmed against the generated OpenAPI create schema). `appRoles` being
+                    // caller-settable is exactly why this path carries an explicit role-ceiling gate — see
+                    // `user-role-administration.custom-impl.backend.service.ts`. An absent `appRoles` falls
+                    // back to the schema default and is NOT treated as a caller grant.
                 }
             ],
             userNotifications: [
@@ -137,9 +376,21 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, users manage themselves via USER_SELF
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
-                    // DTOs auto-derived from decorators (excludeFromUpdate on _id, email, createdAt, updatedAt)
-                    // status and appRoles still manually excluded for this variant
+                    // DTOs auto-derived from decorators. Only `appRoles` and `userTypes`
+                    // remain writable: `_id`, `email`, `status`, `scheduledReactivationAt`
+                    // and timestamps all carry `excludeFromUpdate()`.
+                    //
+                    // Because `appRoles` is caller-settable here, this path is
+                    // the one that actually grants application authority, and it carries the role-ceiling gate
+                    // plus a USER_APP_ROLES_CHANGED audit event (`user-role-administration.custom-impl`).
+                    //
+                    // This whole-array REPLACE is why the additive `assign_roles` / subtractive `revoke_roles`
+                    // verbs are not redundant with it: reaching the same end-state here requires a
+                    // read-modify-write that races with, and silently clobbers, a concurrent edit.
                 }
             ],
             userNotifications: [
@@ -149,13 +400,54 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                 }
             ]
         },
+        [CoreResourceOperation.UPDATE_MANY]: {
+            variants: [
+                {
+                    // The CAPABILITY without a new HTTP surface. `retentionPolicy` requires UPDATE_MANY because
+                    // the impersonalize writer scrubs rows in place through `updateManyAsSystem`. Exposing a bulk
+                    // user update over HTTP would be a genuinely dangerous admin surface (mass role/status
+                    // rewrites), and INTERNAL_CALL registers NO route — like the LIST default above.
+                    //
+                    // ⚠️ INTERNAL_CALL, *not* REPOSITORY_ONLY. Both are route-less, but the three retention
+                    // primitives (`updateManyAsSystem`, `readRetainedAsSystem`, `listRetainedAsSystem`) resolve
+                    // their operation through `getServiceOperationPathDefault`, which matches only INTERNAL_CALL /
+                    // API_CALL / API_CALL_WITH_CALLBACK — REPOSITORY_ONLY is deliberately excluded there and served
+                    // by the separate `getRepositoryOperationPathDefault` transport. A REPOSITORY_ONLY variant here
+                    // therefore satisfies the factory's "UPDATE_MANY exists" guard at boot and then FAILS TO RESOLVE
+                    // when an erasure actually runs. `roles` is inert on a non-URL-bearing variant (role gating is
+                    // bypassed for internal execution); the real gate is the derived `systemAccessPolicy.updateMany`
+                    // grant, which the trusted writer is fail-closed on.
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.CRITICAL,
+                }
+            ],
+        },
         [CoreResourceOperation.DELETE]: {
             variants: [
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, critical risk
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.CRITICAL,
+                    // Irreversible identity destruction — the caller must prove they are still themselves,
+                    // not merely that they held a session at some point. `riskLevel: CRITICAL` above does NOT
+                    // do this: it drives danger-zone placement and typed confirmation in the UI and is read by
+                    // no authorization code. Nor does the per-user-type `stepUpAuth` policy, which is opt-in,
+                    // off by default and satisfied by any authentication newer than `maxAgeSeconds`.
+                    //
+                    // The audience is the reason this one is safe to gate first: `APP_ADMIN_SUPER_ADMIN` is an
+                    // APPLICATION-level authority, whereas the population that provably cannot step up —
+                    // directory-managed (SCIM) users, whose `passwordHash` and passkeys the framework
+                    // deliberately destroys in `_reconcileLocalCredentialsForDirectoryManaged` — is
+                    // ORGANIZATION-scoped by construction.
+                    //
+                    // assurance-control: WILDO.IDENTITY.STEP_UP_AUTHENTICATION — re-authentication before a high-impact action.
+                    requiresStepUpAuthentication: true,
                 }
             ],
             userNotifications: [
@@ -171,8 +463,15 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, high risk - affects permissions
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.HIGH,
                     resourceOperationLike: CoreResourceOperation.UPDATE,
+                    // ADDITIVE grant. `roles` is the REQUEST contract; the custom implementation translates it
+                    // into a union over the persisted `appRoles` array, gates it against the caller's own role
+                    // ceiling, and emits USER_APP_ROLES_CHANGED. Before that implementation existed, `roles`
+                    // named no schema path, so the generic core UPDATE persisted nothing and answered 200.
                     requestDto: z.object({
                         roles: z.array(AppRolesSchema).min(1),
                         reason: z.string().max(500).optional()
@@ -192,8 +491,15 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, high risk - affects permissions
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.HIGH,
                     resourceOperationLike: CoreResourceOperation.UPDATE,
+                    // SUBTRACTIVE revocation — a set difference against the persisted `appRoles`, never a blind
+                    // overwrite. Ceiling-gated like the grant: an administrator who may not GRANT a role must
+                    // not be able to STRIP it either, or the cheapest attack on a privileged account is to
+                    // remove the authority of whoever could intervene.
                     requestDto: z.object({
                         roles: z.array(AppRolesSchema).min(1),
                         reason: z.string().max(500).optional()
@@ -213,8 +519,14 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, high risk - affects access
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.HIGH,
                     resourceOperationLike: CoreResourceOperation.UPDATE,
+                    // Implemented by the shared status-transition factory. `suspensionDuration` is in DAYS
+                    // and is resolved to an absolute `scheduledReactivationAt` at write time — a duration is
+                    // meaningless without the moment it is counted from, and the row records no such moment.
                     requestDto: z.object({
                         reason: z.string().min(1).max(500),
                         suspensionDuration: z.number().min(1).optional(), // Days
@@ -238,8 +550,20 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, medium risk
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                     resourceOperationLike: CoreResourceOperation.UPDATE,
+                    // Implemented by the shared status-transition factory (SUSPENDED → ACTIVE), which also
+                    // clears any pending `scheduledReactivationAt` so a manual unsuspend does not leave the
+                    // sweep's deadline behind for a later suspension to inherit.
+                    //
+                    // MEDIUM is below `AUTOMATIC_AUDIT_RISK_FLOOR`, so without this declaration the trail
+                    // would record every suspension (HIGH) and none of the reinstatements — leaving an
+                    // account that was suspended and cleared reading as still suspended.
+                    // assurance-control: WILDO.ACCESS.PRIVILEGE_EVIDENCE
+                    auditableEvent: { auditBelowRiskFloor: true },
                     requestDto: z.object({
                         reason: z.string().max(500).optional(),
                         notifyUser: z.boolean().default(true)
@@ -256,56 +580,63 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                 }
             ]
         },
+        /**
+         * Administrator-compelled credential reset.
+         *
+         * Implemented by `createUserForcePasswordResetFactories`, which mints a single-use
+         * PASSWORD_RESET token for the target, mails the reset link to the TARGET, revokes the
+         * target's live sessions, and emits `USER_PASSWORD_RESET_FORCED` naming the acting
+         * administrator and their reason.
+         *
+         * Three fields the original declaration carried are deliberately gone:
+         *
+         *  - **`customResponseDto: { resetToken, resetUrl }`** — an account-takeover primitive. An
+         *    administrator holding the link can set the user's password and then authenticate AS
+         *    them; with no actor claim on a session JWT, nothing downstream could tell that apart
+         *    from a genuine login, and the owner would never be told. The link now goes only to the
+         *    account owner's inbox, and the response carries non-secret metadata.
+         *  - **`resetExpirationHours` (1–168)** — a caller-widenable credential-recovery window is a
+         *    persistence mechanism, not a recovery one. The TTL is now a framework policy constant.
+         *  - **`notifyUser`** — notifying the owner is the MECHANISM (the mail carries the only copy
+         *    of the link), not an option an operator can decline.
+         *
+         * `reason` stays and is mandatory: it is what an auditor reads when asking why a credential
+         * was reset out-of-band.
+         *
+         * assurance-control: WILDO.IDENTITY.CREDENTIAL_LIFECYCLE — privileged credential
+         * intervention is authorized, attributable, justified, and evicts existing access.
+         */
         [Users_Operations.FORCE_PASSWORD_RESET]: {
             variants: [
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, high risk - affects authentication
+                    // Administers ANOTHER user — see `admitsCrossSubjectUserAdministration`. The caller is still
+                    // gated by `roles` above; this only admits the SUBJECT to be someone other than the caller.
+                    admitsCrossSubjectUserAdministration: true,
                     riskLevel: ResourceOperationRiskLevel.HIGH,
                     resourceOperationLike: CoreResourceOperation.UPDATE,
                     requestDto: z.object({
-                        reason: z.string().min(1).max(500),
-                        notifyUser: z.boolean().default(true),
-                        resetExpirationHours: z.number().min(1).max(168).default(24) // 1-168 hours (1 week max)
-                    }),
-                    customResponseDto: z.object({
-                        resetToken: z.string(),
-                        resetUrl: z.url(),
-                        expiresAt: z.date()
-                    }),
-                }
-            ],
-            userNotifications: [
-                {
-                    target: CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR,
-                    channel: CoreUserNotificationChannel.EMAIL,
-                }
-            ]
-        },
-        [Users_Operations.IMPERSONATE]: {
-            variants: [
-                {
-                    variantType: ResourceOperationVariantType.API_CALL,
-                    isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, critical risk - assumes user identity
-                    riskLevel: ResourceOperationRiskLevel.CRITICAL,
-                    resourceOperationLike: CoreResourceOperation.READ,
-                    requestDto: z.object({
-                        reason: z.string().min(1).max(500),
-                        durationMinutes: z.number().min(1).max(480).default(60), // Max 8 hours
-                        auditLog: z.boolean().default(true)
+                        reason: z.string().min(1).max(500)
                     }),
                     customResponseDto: z.object({
-                        impersonationToken: z.string(),
+                        /** When the emailed reset link stops working. Non-secret — the link itself is not returned. */
                         expiresAt: z.date(),
-                        auditId: z.string()
+                        /** Always true today; explicit so the caller can see the eviction happened. */
+                        sessionsRevoked: z.boolean()
                     }),
+                    // A deleted identity has no credential path worth resetting; the service rejects it
+                    // with a 409. Hides the roster action rather than letting it 409 on click.
                     enabledCondition: ({ currentObject }) => {
-                        return currentObject.status === UserStatus.ACTIVE;
+                        return currentObject.status !== UserStatus.DELETED;
                     }
                 }
             ],
+            // The ADMIN-AUDIT copy. The user-facing reset mail is the system PASSWORD_RESET template
+            // dispatched by the auth service when the token is minted — deliberately not duplicated
+            // into this resource-operation fan-out, which would create a second reset email that can
+            // drift from the one the self-service flow sends.
             userNotifications: [
                 {
                     target: CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR,
@@ -313,102 +644,6 @@ export const usersResourceConfiguration_InitializationFactory = (resourcesRelati
                 }
             ]
         },
-        [Users_Operations.MERGE_ACCOUNTS]: {
-            variants: [
-                {
-                    variantType: ResourceOperationVariantType.API_CALL,
-                    isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, critical risk - data consolidation
-                    riskLevel: ResourceOperationRiskLevel.CRITICAL,
-                    resourceOperationLike: CoreResourceOperation.UPDATE,
-                    requestDto: z.object({
-                        targetUserId: z.string().min(1),
-                        keepPrimaryUser: z.enum(['source', 'target']).default('target'),
-                        mergeProfile: z.boolean().default(true),
-                        mergePreferences: z.boolean().default(false),
-                        mergeOrganizations: z.boolean().default(true),
-                        reason: z.string().min(1).max(500)
-                    }),
-                    customResponseDto: z.object({
-                        mergedUser: UserSchema,
-                        removedUserId: z.string(),
-                        mergedDataSummary: z.object({
-                            organizationMemberships: z.number(),
-                            dataPoints: z.number(),
-                            mergedAt: z.date()
-                        })
-                    }),
-                }
-            ],
-            userNotifications: [
-                {
-                    target: CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR,
-                    channel: CoreUserNotificationChannel.EMAIL,
-                }
-            ]
-        },
-        [Users_Operations.EXPORT_USER_DATA]: {
-            variants: [
-                {
-                    variantType: ResourceOperationVariantType.API_CALL,
-                    isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, medium risk
-                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
-                    resourceOperationLike: CoreResourceOperation.READ,
-                    requestDto: z.object({
-                        format: z.enum(['json', 'csv', 'pdf']).default('json'),
-                        includePersonalData: z.boolean().default(true),
-                        includeActivityData: z.boolean().default(true),
-                        includeOrganizationData: z.boolean().default(true),
-                        includeAdminData: z.boolean().default(false),
-                        dateRange: z.object({
-                            startDate: z.date().optional(),
-                            endDate: z.date().optional()
-                        }).optional()
-                    }),
-                    customResponseDto: z.object({
-                        downloadUrl: z.url(),
-                        expiresAt: z.date(),
-                        fileSize: z.number(),
-                        recordCount: z.number()
-                    }),
-                }
-            ],
-            userNotifications: [
-                {
-                    target: CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR,
-                    channel: CoreUserNotificationChannel.EMAIL,
-                }
-            ]
-        },
-        [Users_Operations.SEND_INVITATION]: {
-            variants: [
-                {
-                    variantType: ResourceOperationVariantType.API_CALL,
-                    isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // v1: admin-only, medium risk
-                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
-                    resourceOperationLike: CoreResourceOperation.CREATE,
-                    requestDto: z.object({
-                        email: z.email(),
-                        roles: z.array(AppRolesSchema).default([]),
-                        personalMessage: z.string().max(500).optional(),
-                        expirationDays: z.number().min(1).max(30).default(7)
-                    }),
-                    customResponseDto: z.object({
-                        invitationId: z.string(),
-                        invitationUrl: z.url(),
-                        expiresAt: z.date()
-                    }),
-                }
-            ],
-            userNotifications: [
-                {
-                    target: CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR,
-                    channel: CoreUserNotificationChannel.EMAIL,
-                }
-            ]
-        }
     },
 });
-//# sourceMappingURL=users.shared.resources-config.schemas.js.map
+//# sourceMappingURL=users.shared.resources-config.schemas.js.map