@stapel/workspaces-react 0.7.0 → 0.9.0

package/src/api/types.ts

@@ -9,11 +9,15 @@
  * openapi-typescript under-describe the runtime, apply a small documented
  * correction (see auth-react `api/types.ts` for the three canonical patterns).
  */
-import type { components } from "./generated/schema.js";
+import type { components, operations } from "./generated/schema.js";
 
 /** The generated schema table — the one source of truth for wire shapes. */
 export type Schemas = components["schemas"];
 
+/** The generated operation table — the source of truth for QUERY parameters
+ * (drf-spectacular declares them per-operation, not as a component schema). */
+export type Operations = operations;
+
 // ── aliases (the stapel-workspaces schemas this pair uses) ────────────────────
 
 /** One workspace — identity, storage, my role, member count (GET/POST/PATCH). */
@@ -34,8 +38,21 @@ export type MemberInvite = Schemas["MemberInviteRequest"];
 export type MemberInviteResult = Schemas["MemberInviteResponse"];
 /** PATCH /{id}/members/{userId} request body — the new role. */
 export type MemberRoleUpdate = Schemas["PatchedMemberUpdateRequest"];
-/** One pending/accepted invitation (a row of {@link MemberInviteResult}). */
+/** One pending/accepted invitation (a row of {@link MemberInviteResult}, and
+ * a row of the admin's invitation table — GET /{id}/invitations). The invite
+ * TOKEN is deliberately absent from this shape: it is a bearer credential
+ * that only ever leaves the backend inside the invitation email. */
 export type Invitation = Schemas["InvitationResponse"];
+/** GET /{id}/invitations 200 body — an anchor-paginated page of {@link Invitation}s. */
+export type InvitationPage = Schemas["PaginatedInvitationResponseList"];
+/** POST /{id}/members/{userId}/password/reset request body — an optional
+ * admin-chosen password, the first-login demands to raise, and an audit note. */
+export type MemberPasswordReset = Schemas["MemberPasswordResetRequest"];
+/** POST /{id}/members/{userId}/password/reset 200 body. `generated_password`
+ * is a ONE-SHOT credential (present only when the request omitted `password`)
+ * — see {@link "../model/mutations.js".useResetMemberPassword}, which keeps it
+ * out of the query cache. */
+export type MemberPasswordResetResult = Schemas["MemberPasswordResetResponse"];
 /** POST /invitations/accept request body — the token from the email link. */
 export type InvitationAccept = Schemas["InvitationAcceptRequest"];
 /** GET /invitations/{token} 200 body — the public (AllowAny) preview the
@@ -51,6 +68,14 @@ export type RoleInfo = Schemas["RoleResponse"];
 /** GET /roles 200 body — the effective role registry, rank-descending. */
 export type RoleList = Schemas["RoleListResponse"];
 
+/**
+ * Deployment shape: what a person landing "off the street" gets, and
+ * whether self-serve signup is open. A property of the INSTANCE, not of a
+ * workspace — and not a setting the customer can toggle: it's fixed at
+ * deployment time.
+ */
+export type InstanceShape = Schemas["InstanceShapeResponse"];
+
 // ── documented corrections (drf-spectacular under-describes) ──────────────────
 
 /**
@@ -88,3 +113,77 @@ export interface MembersParams {
   /** Case-insensitive substring filter matched against a member's email or display name. */
   readonly search?: string;
 }
+
+/**
+ * Which invitations GET /{id}/invitations returns. Taken VERBATIM from the
+ * generated operation table (not re-typed by hand): `pending` (the backend
+ * default) — live, seat-reserving invitations, i.e. who has not accepted yet;
+ * `never_accepted` — those plus declined / revoked / expired; `all` — the full
+ * history, accepted rows included.
+ */
+export type InvitationStatusFilter = NonNullable<
+  NonNullable<
+    Operations["workspaces_api_v1_invitations_list"]["parameters"]["query"]
+  >["status"]
+>;
+
+/**
+ * Anchor-pagination query for GET /{id}/invitations (core `AnchorPagination`,
+ * the same shape as {@link MembersParams} plus the `status` filter). All
+ * optional: no params fetches the newest page of PENDING invitations
+ * (default limit 100, max 500).
+ *
+ * ANCHOR, not page numbers: a page is addressed by the opaque `next_anchor`
+ * of the page before it. There is no "page 3" to jump to and no offset to
+ * skew when an invitation is revoked mid-scroll.
+ */
+export interface InvitationsParams {
+  /** Anchor value to paginate from (exclusive) — a page's `next_anchor`. */
+  readonly anchor?: string;
+  /** Pagination direction relative to `anchor`. */
+  readonly direction?: "next" | "prev" | "center";
+  /** Page size (default 100, max 500). */
+  readonly limit?: number;
+  /** Case-insensitive substring filter on the invited email address. */
+  readonly search?: string;
+  /** Which invitations to return (default `pending`). */
+  readonly status?: InvitationStatusFilter;
+}
+
+/**
+ * One first-login demand an organization may raise on an account it admits
+ * (`settings.security.provisioned_user_policies`, backend dto
+ * `PROVISIONED_USER_POLICIES`). INDEPENDENT checkboxes, not alternatives — an
+ * org may demand both. NOT GENERATED: the security block lives inside the
+ * free-form `Workspace.settings` JSON, so drf-spectacular types it as an
+ * untyped object; the backend serializer validates exactly these two values.
+ */
+export type ProvisionedUserPolicy = "password_change" | "mfa_enroll";
+
+/**
+ * Typed shape of `Workspace.settings.security` (backend dto
+ * `WorkspaceSecuritySettings`, org-program §C3). A documented correction for
+ * the same reason as {@link WorkspaceRole}: the block is stored inside the
+ * free-form settings JSON (no schema migration on the backend), so the
+ * generated types say `object` and this is the canon of the known keys.
+ * Unknown keys are preserved verbatim by the backend — hence the index
+ * signature, and hence why the update hook MERGES rather than replaces.
+ */
+export interface WorkspaceSecuritySettings {
+  /** Whether membership requires a strong second factor. Turning it on
+   * sweeps current members and suspends those without one (reason `no_mfa`). */
+  readonly require_mfa?: boolean;
+  /**
+   * First-login steps demanded of accounts the org admits — a LIST since
+   * stapel-workspaces 0.13.0 (#90). The pre-0.13 singular
+   * `provisioned_user_policy` string is still read by the backend for old
+   * rows, but this pair only ever WRITES the list: a client that keeps
+   * writing the singular spelling silently caps the org at one demand.
+   */
+  readonly provisioned_user_policies?: readonly ProvisionedUserPolicy[];
+  /** Derived, read-only: whether the org actually set the policies (as
+   * opposed to inheriting the `password_change` default). Never sent. */
+  readonly policies_configured?: boolean;
+  /** Extra keys pass through the backend verbatim (client extension). */
+  readonly [extra: string]: unknown;
+}

package/src/api/workspacesApi.ts

@@ -1,14 +1,20 @@
 import type { StapelClient, StapelRequestOptions } from "@stapel/core";
 import type {
+  Invitation,
+  InvitationPage,
+  InvitationsParams,
   Member,
   MemberInvite,
   MemberInviteResult,
   MemberPage,
+  MemberPasswordReset,
+  MemberPasswordResetResult,
   MemberRoleUpdate,
   MembersParams,
   InvitationAccept,
   InvitationClaim,
   InvitationPreview,
+  InstanceShape,
   RoleList,
   Workspace,
   WorkspaceCreate,
@@ -87,6 +93,55 @@ export interface WorkspacesApi {
   /** Remove a member from a workspace (admin+; the last owner is protected). */
   removeMember(workspaceId: string, userId: string): Promise<void>;
 
+  /**
+   * Reset a member's password on the organization's order (stapel-workspaces
+   * ≥0.14.0, #110). Capability `members.password.reset`, declared **high** —
+   * the backend wraps it in `requires_verification(scope="sensitive")`, so an
+   * ambient cookie is not enough and a step-up (or factor ENROLLMENT) 403 is
+   * the normal first answer. A missing/wrong target answers one
+   * byte-identical 404 (never an existence oracle).
+   *
+   * `generated_password` in the reply is a ONE-SHOT credential: present only
+   * when the request omitted `password`, never re-fetchable, never logged.
+   */
+  resetMemberPassword(
+    workspaceId: string,
+    userId: string,
+    body?: MemberPasswordReset
+  ): Promise<MemberPasswordResetResult>;
+
+  // ── invitation administration (#109, stapel-workspaces ≥0.12.0) ────────────
+
+  /**
+   * The workspace's invitations — the admin's "who has not accepted yet"
+   * table (capability `members.invite`). An ANCHOR-paginated page, filtered
+   * by `status` (default `pending`) and `search` (invited email). The invite
+   * token is never in the response.
+   */
+  listInvitations(
+    workspaceId: string,
+    params?: InvitationsParams
+  ): Promise<InvitationPage>;
+  /**
+   * Withdraw a live invitation — the workspace's terminal "no", the mirror of
+   * the invitee's decline (the two stay distinguishable in `status` forever).
+   * Only a `pending` one is revocable; the reply is the updated row.
+   */
+  revokeInvitation(
+    workspaceId: string,
+    invitationId: string
+  ): Promise<Invitation>;
+  /**
+   * Send the invitation email again. Accepts an EXPIRED invitation on purpose
+   * (a dead TTL is the commonest reason to resend) and refuses the three
+   * terminal states. Rotates the token and restarts the TTL — every earlier
+   * link stops working — so the reply is the updated row, not the old one.
+   */
+  resendInvitation(
+    workspaceId: string,
+    invitationId: string
+  ): Promise<Invitation>;
+
   /** Accept an invitation by its token — returns the caller's new membership. */
   acceptInvitation(body: InvitationAccept): Promise<Member>;
 
@@ -117,6 +172,9 @@ export interface WorkspacesApi {
   /** The effective role registry (builtin + deployment overlay), for
    * RoleSelect-class UI — capability strings verbatim, rank-descending. */
   listRoles(): Promise<RoleList>;
+
+  /** Instance shape (GET /instance, unauthenticated). */
+  getInstanceShape(): Promise<InstanceShape>;
 }
 
 export function createWorkspacesApi(client: StapelClient): WorkspacesApi {
@@ -172,6 +230,39 @@ export function createWorkspacesApi(client: StapelClient): WorkspacesApi {
         mutating()
       ),
 
+    resetMemberPassword: (workspaceId, userId, body) =>
+      client.post(
+        `/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(userId)}/password/reset`,
+        (body ?? {}) satisfies MemberPasswordReset,
+        mutating()
+      ),
+
+    listInvitations: (workspaceId, params) => {
+      const query: Record<string, string | number> = {};
+      if (params?.anchor !== undefined) query.anchor = params.anchor;
+      if (params?.direction !== undefined) query.direction = params.direction;
+      if (params?.limit !== undefined) query.limit = params.limit;
+      if (params?.search !== undefined) query.search = params.search;
+      if (params?.status !== undefined) query.status = params.status;
+      return client.get(`/${encodeURIComponent(workspaceId)}/invitations`, {
+        query,
+      });
+    },
+
+    revokeInvitation: (workspaceId, invitationId) =>
+      client.post(
+        `/${encodeURIComponent(workspaceId)}/invitations/${encodeURIComponent(invitationId)}/revoke`,
+        undefined,
+        mutating()
+      ),
+
+    resendInvitation: (workspaceId, invitationId) =>
+      client.post(
+        `/${encodeURIComponent(workspaceId)}/invitations/${encodeURIComponent(invitationId)}/resend`,
+        undefined,
+        mutating()
+      ),
+
     acceptInvitation: (body) =>
       client.post(
         "/invitations/accept",
@@ -197,5 +288,7 @@ export function createWorkspacesApi(client: StapelClient): WorkspacesApi {
       ),
 
     listRoles: () => client.get("/roles"),
+
+    getInstanceShape: () => client.get("/instance"),
   };
 }

package/src/default/MembersManager.tsx

@@ -1,7 +1,7 @@
 /**
  * `<MembersManager/>` — default skin for the "members & roles" settings
- * screen (owner directive: "настройки воркспейса (имя/участники/роли/
- * инвайты)"). Built entirely on this pair's EXISTING `Members` headless
+ * screen (owner directive: workspace settings — name/members/roles/
+ * invites). Built entirely on this pair's EXISTING `Members` headless
  * wrapper (`useMembers`/`useInviteMembers`/`useUpdateMemberRole`/
  * `useRemoveMember`) — no new backend surface.
  *

package/src/i18n/generated/errors.gen.ts

@@ -72,6 +72,7 @@ export const WORKSPACES_ERRORS = {
   "error.403.membership_suspended": { status: 403, params: ["reason"], remediation: "fix_input", en: "Your membership in this workspace is suspended ({reason})" },
   "error.403.missing_capability": { status: 403, params: ["capability"], remediation: "contact_support", en: "Your role does not include the {capability} capability in this workspace" },
   "error.403.network_blocked": { status: 403, params: [], remediation: "contact_support", en: "Requests from this network are not allowed" },
+  "error.403.role_exceeds_inviter_rank": { status: 403, params: ["role"], remediation: "fix_input", en: "You cannot grant a role that outranks your own ({role})" },
   "error.403.verification_enrollment_required": { status: 403, params: [], remediation: "verify", en: "Verification factor enrollment required" },
   "error.403.verification_required": { status: 403, params: [], remediation: "verify", en: "Additional verification required" },
   "error.404.ad_not_found": { status: 404, params: [], remediation: "retry", en: "Listing not found" },
@@ -138,6 +139,7 @@ export const WORKSPACES_ERROR_CODES: readonly WorkspacesErrorCode[] = [
   "error.403.membership_suspended",
   "error.403.missing_capability",
   "error.403.network_blocked",
+  "error.403.role_exceeds_inviter_rank",
   "error.403.verification_enrollment_required",
   "error.403.verification_required",
   "error.404.ad_not_found",
@@ -206,6 +208,7 @@ export const workspacesErrorBundleEn: Record<WorkspacesErrorCode, string> = {
   "error.403.membership_suspended": "Your membership in this workspace is suspended ({reason})",
   "error.403.missing_capability": "Your role does not include the {capability} capability in this workspace",
   "error.403.network_blocked": "Requests from this network are not allowed",
+  "error.403.role_exceeds_inviter_rank": "You cannot grant a role that outranks your own ({role})",
   "error.403.verification_enrollment_required": "Verification factor enrollment required",
   "error.403.verification_required": "Additional verification required",
   "error.404.ad_not_found": "Listing not found",

package/src/i18n/generated/errors.json

@@ -290,6 +290,15 @@
     "remediation": "contact_support",
     "en": "Requests from this network are not allowed"
   },
+  {
+    "code": "error.403.role_exceeds_inviter_rank",
+    "status": 403,
+    "params": [
+      "role"
+    ],
+    "remediation": "fix_input",
+    "en": "You cannot grant a role that outranks your own ({role})"
+  },
   {
     "code": "error.403.verification_enrollment_required",
     "status": 403,

package/src/i18n/generated/errors.ru.gen.ts

@@ -49,6 +49,7 @@ export const workspacesErrorBundleRu: Record<WorkspacesErrorCode, string> = {
   "error.403.membership_suspended": "Ваше членство в этом рабочем пространстве приостановлено ({reason})",
   "error.403.missing_capability": "Ваша роль не включает право {capability} в этом рабочем пространстве",
   "error.403.network_blocked": "Запросы из этой сети не разрешены.",
+  "error.403.role_exceeds_inviter_rank": "Вы не можете выдать роль, которая превышает вашу собственную ({role})",
   "error.403.verification_enrollment_required": "Требуется регистрация фактора подтверждения.",
   "error.403.verification_required": "Требуется дополнительная проверка",
   "error.404.ad_not_found": "Объявление не найдено",

package/src/index.ts

@@ -57,14 +57,28 @@ export {
   useWorkspaces,
   useWorkspace,
   useMembers,
+  useInvitations,
+  useInfiniteInvitations,
   useRoles,
+  useInstanceShape,
   useInvitationPreview,
   useCapabilities,
+  useCapabilityGate,
 } from "./model/queries.js";
-export type { CapabilitiesResult } from "./model/queries.js";
+export type { CapabilitiesResult, CapabilityGate } from "./model/queries.js";
 
 // ── model (capability matcher + email-mask ports — backend-synced utils) ─────
 export { capabilityMatches, hasCapability } from "./model/capabilities.js";
+export {
+  BUILTIN_CAPABILITY_LEVELS,
+  SENSITIVE_SCOPE,
+  capabilityLevel,
+  readVerificationEnrollment,
+} from "./model/stepUp.js";
+export type {
+  CapabilityLevel,
+  VerificationEnrollment,
+} from "./model/stepUp.js";
 export { maskEmail, emailMatchesMask } from "./model/emailMask.js";
 
 // ── model (write hooks) ──────────────────────────────────────────────────────
@@ -78,8 +92,15 @@ export {
   useAcceptInvitation,
   useClaimInvitation,
   useDeclineInvitation,
+  useRevokeInvitation,
+  useResendInvitation,
+  useResetMemberPassword,
+  useUpdateSecuritySettings,
+} from "./model/mutations.js";
+export type {
+  MemberRoleChange,
+  MemberPasswordResetVars,
 } from "./model/mutations.js";
-export type { MemberRoleChange } from "./model/mutations.js";
 
 // ── api (wire type aliases) ──────────────────────────────────────────────────
 export type {
@@ -94,9 +115,16 @@ export type {
   MemberInviteResult,
   MemberRoleUpdate,
   Invitation,
+  InvitationPage as InvitationListData,
+  InvitationsParams,
+  InvitationStatusFilter,
   InvitationAccept,
   InvitationPreview,
   InvitationClaim,
+  MemberPasswordReset,
+  MemberPasswordResetResult,
+  ProvisionedUserPolicy,
+  WorkspaceSecuritySettings,
   RoleInfo,
   RoleList,
   WorkspaceRole,

package/src/model/mutations.ts

@@ -5,20 +5,24 @@ import type {
 } from "@tanstack/react-query";
 import type { StapelApiError } from "@stapel/core";
 import type {
+  Invitation,
   Member,
   MemberInvite,
   MemberInviteResult,
+  MemberPasswordReset,
+  MemberPasswordResetResult,
   InvitationAccept,
   InvitationClaim,
   Workspace,
   WorkspaceCreate,
+  WorkspaceSecuritySettings,
   WorkspaceUpdate,
 } from "../api/types.js";
 import { useWorkspacesApi } from "./context.js";
 import { workspacesQueryKeys } from "./queryKeys.js";
 
 /**
- * Write hooks (frontend-standard §2 — "мутации с инвалидацией"). Each mutation
+ * Write hooks (frontend-standard §2 — mutations invalidate on success). Each mutation
  * invalidates exactly the server state it can move. Membership and ownership are
  * server truth (roles gate access in other services via the membership cache),
  * so NONE of these are optimistic (frontend-core-architecture §2.6: optimistic
@@ -175,6 +179,194 @@ export function useRemoveMember(
   return useMutation(options);
 }
 
+/**
+ * Withdraw a live invitation (POST /{id}/invitations/{invitationId}/revoke,
+ * #109). The variable is the invitation id; the reply is the UPDATED row, so
+ * it is written straight into the page cache the table reads — a revoke is
+ * the mirror of the invitee's decline and both must stay distinguishable in
+ * `status`, which a blind refetch-and-hope would blur. Only a `pending`
+ * invitation is revocable: the backend answers
+ * `error.400.invitation_already_used` / `_revoked` / `_expired` otherwise
+ * (each its own key, not a shrug). Also refreshes the member list — the seat
+ * the invitation reserved is freed on commit.
+ */
+export function useRevokeInvitation(
+  workspaceId: string
+): UseMutationResult<Invitation, StapelApiError, string> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<Invitation, StapelApiError, string> = {
+    mutationFn: (invitationId) =>
+      api.revokeInvitation(workspaceId, invitationId),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitations(workspaceId),
+      });
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.members(workspaceId),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/**
+ * Send the invitation email again (POST /{id}/invitations/{invitationId}/resend,
+ * #109). The variable is the invitation id.
+ *
+ * This is NOT an idempotent "poke": the backend rotates the token and
+ * restarts the TTL, so every earlier link — including the one already in the
+ * invitee's inbox — stops working, and the row's `expires_at` moves. Hence
+ * the invalidation: a table still showing the old expiry would be lying about
+ * a live credential. An EXPIRED invitation is accepted on purpose (a dead TTL
+ * is the commonest reason to resend); reviving it re-reserves a seat, so a
+ * plan ceiling can answer 402 here.
+ */
+export function useResendInvitation(
+  workspaceId: string
+): UseMutationResult<Invitation, StapelApiError, string> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<Invitation, StapelApiError, string> = {
+    mutationFn: (invitationId) =>
+      api.resendInvitation(workspaceId, invitationId),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitations(workspaceId),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/** The variable for {@link useResetMemberPassword}: whose password, and the
+ * (optional) body — omit `password` to have the server generate one. */
+export interface MemberPasswordResetVars {
+  readonly userId: string;
+  readonly body?: MemberPasswordReset;
+}
+
+/**
+ * Reset a member's password on the organization's order
+ * (POST /{id}/members/{userId}/password/reset, #110).
+ *
+ * **Step-up before the button.** Capability `members.password.reset` is
+ * declared `high`, so the backend wraps the endpoint in
+ * `requires_verification(scope="sensitive")`. Ask
+ * {@link "./queries.js".useCapabilityGate}(workspaceId,
+ * "members.password.reset") BEFORE offering the affordance: it answers both
+ * "may this caller" and "will a step-up be demanded". A step-up CHALLENGE is
+ * then driven by core's client and replayed transparently; the one case that
+ * is not transparent is the ENROLLMENT demand (the caller holds no factor to
+ * challenge) — read it off `error` with
+ * {@link "./stepUp.js".readVerificationEnrollment} and route to enrollment.
+ *
+ * **The one-shot credential.** `generated_password` comes back exactly once,
+ * only when the request omitted `password`, and can never be re-fetched. It
+ * is therefore deliberately kept OUT of the query cache: nothing here writes
+ * the response with `setQueryData`, and `gcTime: 0` drops the mutation result
+ * the moment the screen showing it unmounts. Writing it to a query would
+ * mean writing a live credential into every devtools panel AND into
+ * `localStorage`, because core's query runtime persists the whole per-user
+ * query cache (`createStapelQueryClient`). Hand it to the member out of band.
+ *
+ * Refreshes the member list (the reset moves the member's first-login state);
+ * a target that is not a resettable member of THIS workspace answers one
+ * byte-identical 404, never an existence oracle.
+ */
+export function useResetMemberPassword(
+  workspaceId: string
+): UseMutationResult<
+  MemberPasswordResetResult,
+  StapelApiError,
+  MemberPasswordResetVars
+> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    MemberPasswordResetResult,
+    StapelApiError,
+    MemberPasswordResetVars
+  > = {
+    mutationFn: ({ userId, body }) =>
+      api.resetMemberPassword(workspaceId, userId, body),
+    // The result carries a live credential: never retained past the screen
+    // that displays it, and never persisted.
+    gcTime: 0,
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.members(workspaceId),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/**
+ * Update a workspace's SECURITY settings (the `security` block of
+ * `PATCH /{id}`, org-program §C3) — `require_mfa` and the first-login
+ * `provisioned_user_policies`.
+ *
+ * Separate from {@link useUpdateWorkspace} because the backend treats this
+ * block as a different endpoint in all but the URL: an extra capability
+ * (`workspace.security.manage`, declared `high`) plus a step-up on the same
+ * `sensitive` scope as the password reset, and turning `require_mfa` on
+ * sweeps the current members. See {@link useResetMemberPassword} for how to
+ * wire that in front of the control.
+ *
+ * `provisioned_user_policies` is a LIST since stapel-workspaces 0.13.0 (#90)
+ * — independent checkboxes, not alternatives. An explicit `[]` is a
+ * deliberate, auditable choice ("demand nothing"), so it is sent as such and
+ * never dropped as "empty means unset".
+ *
+ * MERGES, because the backend does not: `PATCH` assigns `settings` wholesale
+ * (`ws.settings = data.settings`), so sending a bare `{security: …}` would
+ * silently drop every other key the workspace holds. The merge reads the
+ * workspace fresh rather than trusting the detail cache — a stale snapshot
+ * here would resurrect settings somebody else has since removed.
+ */
+export function useUpdateSecuritySettings(
+  workspaceId: string
+): UseMutationResult<Workspace, StapelApiError, WorkspaceSecuritySettings> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    Workspace,
+    StapelApiError,
+    WorkspaceSecuritySettings
+  > = {
+    mutationFn: async (patch) => {
+      const current = await api.getWorkspace(workspaceId);
+      const settings = (current.settings ?? {}) as Record<string, unknown>;
+      const security = (settings["security"] ?? {}) as Record<string, unknown>;
+      // `policies_configured` is derived and read-only on the wire — never
+      // sent back, whatever a caller spread into the patch.
+      const { policies_configured: _derived, ...writable } = {
+        ...security,
+        ...patch,
+      };
+      return api.updateWorkspace(workspaceId, {
+        settings: { ...settings, security: writable },
+      });
+    },
+    onSuccess: (updated) => {
+      queryClient.setQueryData(
+        workspacesQueryKeys.detail(workspaceId),
+        updated
+      );
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.list(),
+      });
+      // require_mfa ON suspends members without a strong factor; OFF lifts
+      // those suspensions. Either way the roster just moved.
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.members(workspaceId),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
 /**
  * Accept an invitation by its token — the caller joins the workspace. A dead
  * token surfaces a localizable `StapelApiError` (`error.400.invitation_expired`