@stapel/workspaces-react 0.7.0 → 0.8.0

package/src/index.ts

@@ -57,14 +57,27 @@ export {
   useWorkspaces,
   useWorkspace,
   useMembers,
+  useInvitations,
+  useInfiniteInvitations,
   useRoles,
   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 +91,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 +114,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,13 +5,17 @@ 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";
@@ -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`

package/src/model/queries.ts

@@ -1,9 +1,15 @@
-import { useQuery } from "@tanstack/react-query";
-import type { UseQueryResult } from "@tanstack/react-query";
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import type {
+  InfiniteData,
+  UseInfiniteQueryResult,
+  UseQueryResult,
+} from "@tanstack/react-query";
 import { useActiveSessionReady } from "@stapel/core";
 import type { StapelApiError } from "@stapel/core";
 import type {
+  InvitationPage,
   InvitationPreview,
+  InvitationsParams,
   MemberPage,
   MembersParams,
   RoleInfo,
@@ -13,6 +19,8 @@ import type {
 import { useWorkspacesApi } from "./context.js";
 import { workspacesQueryKeys } from "./queryKeys.js";
 import { hasCapability } from "./capabilities.js";
+import { SENSITIVE_SCOPE, capabilityLevel } from "./stepUp.js";
+import type { CapabilityLevel } from "./stepUp.js";
 
 /**
  * Read hooks over the workspaces API. Staleness follows core's query defaults;
@@ -81,6 +89,70 @@ export function useMembers(
   });
 }
 
+/**
+ * One page of a workspace's invitations (GET /{id}/invitations, #109) — the
+ * admin's "who has not accepted yet" table. Disabled until a `workspaceId` is
+ * given (and the session is ready — see {@link useWorkspace}).
+ *
+ * ANCHOR pagination, exactly like {@link useMembers}: pass a page's
+ * `next_anchor` as `anchor` to walk forward. There is no page NUMBER — an
+ * offset would skew the moment an invitation is revoked or accepted while the
+ * admin is reading, which on this screen is the normal case, not the edge one.
+ * For scroll-to-load-more use {@link useInfiniteInvitations}.
+ *
+ * `status` defaults to the backend's `pending` (live, seat-reserving
+ * invitations); pass `never_accepted` to include declined/revoked/expired, or
+ * `all` for the full history.
+ */
+export function useInvitations(
+  workspaceId: string | null,
+  params?: InvitationsParams
+): UseQueryResult<InvitationPage, StapelApiError> {
+  const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
+  const p = params ?? {};
+  return useQuery({
+    queryKey: workspacesQueryKeys.invitationsPage(workspaceId ?? "", p),
+    queryFn: () => api.listInvitations(workspaceId as string, p),
+    enabled: sessionReady && workspaceId !== null && workspaceId !== "",
+  });
+}
+
+/**
+ * A workspace's invitations as an infinite (load-more) list. Follows the
+ * backend's ANCHOR pagination and nothing else: the page param IS the
+ * previous page's `next_anchor`, and the walk stops when `has_next` goes
+ * false. `data.pages.flatMap(p => p.items)` is the flat row list.
+ *
+ * `filters` (`status` / `search` / `limit`) are part of the query key, so
+ * flipping the status tab starts a fresh anchor walk rather than appending
+ * rows of one filter to the pages of another.
+ */
+export function useInfiniteInvitations(
+  workspaceId: string | null,
+  filters?: Omit<InvitationsParams, "anchor" | "direction">
+): UseInfiniteQueryResult<
+  InfiniteData<InvitationPage, string | undefined>,
+  StapelApiError
+> {
+  const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
+  const f = filters ?? {};
+  return useInfiniteQuery({
+    queryKey: workspacesQueryKeys.invitationsInfinite(workspaceId ?? "", f),
+    queryFn: ({ pageParam }) =>
+      api.listInvitations(workspaceId as string, {
+        ...f,
+        direction: "next",
+        ...(pageParam !== undefined ? { anchor: pageParam } : {}),
+      }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (last) =>
+      last.has_next ? (last.next_anchor ?? undefined) : undefined,
+    enabled: sessionReady && workspaceId !== null && workspaceId !== "",
+  });
+}
+
 /**
  * The effective role registry (GET /roles, org-program §A2): builtin four +
  * the deployment's `STAPEL_WORKSPACES["ROLES"]` overlay, capability strings
@@ -150,3 +222,61 @@ export function useCapabilities(workspaceId: string | null): CapabilitiesResult
     error: query.error ?? null,
   };
 }
+
+/** What {@link useCapabilityGate} answers about ONE capability, BEFORE the
+ * operation is attempted. */
+export interface CapabilityGate {
+  /** The capability asked about, verbatim. */
+  readonly capability: string;
+  /** Does the caller's role carry it? Deny-by-default while loading. */
+  readonly allowed: boolean;
+  /** Its declared step-up level (ported registry — see `./stepUp.js`). */
+  readonly level: CapabilityLevel;
+  /** True when `level === "high"`: the backend ALSO demands a fresh
+   * verification (scope {@link SENSITIVE_SCOPE}) on top of the capability. */
+  readonly requiresStepUp: boolean;
+  /** The verification scope of that demand, or `null` at `standard`. */
+  readonly stepUpScope: string | null;
+  readonly isLoading: boolean;
+}
+
+/**
+ * Ask about one capability BEFORE offering the operation (org-program §A3).
+ *
+ * Two different answers, both needed in front of the button rather than
+ * behind it:
+ *
+ * * `allowed` — the caller's role carries the mandate. UI convenience only,
+ *   deny-by-default; the backend re-checks. This is what replaces guessing
+ *   access from the ROLE NAME: a deployment role like `secretary` can hold
+ *   `members.invite` and would still fail a `role === "admin"` test forever,
+ *   no matter what the registry says.
+ * * `requiresStepUp` — the operation is declared `high`, so a fresh step-up
+ *   verification is demanded on top. Knowing this up front is what lets a
+ *   screen say "you'll be asked to confirm" (or pre-drive enrollment)
+ *   instead of showing a button that answers 403.
+ *
+ * Example — the administrative password reset:
+ * ```tsx
+ * const gate = useCapabilityGate(workspaceId, "members.password.reset");
+ * // gate.allowed === false  → do not render the button at all
+ * // gate.requiresStepUp     → render it with the "we will ask you to
+ * //                           confirm" affordance, wired to the app's
+ * //                           verification controller
+ * ```
+ */
+export function useCapabilityGate(
+  workspaceId: string | null,
+  capability: string
+): CapabilityGate {
+  const { can, isLoading } = useCapabilities(workspaceId);
+  const level = capabilityLevel(capability);
+  return {
+    capability,
+    allowed: can(capability),
+    level,
+    requiresStepUp: level === "high",
+    stepUpScope: level === "high" ? SENSITIVE_SCOPE : null,
+    isLoading,
+  };
+}

package/src/model/queryKeys.ts

@@ -1,4 +1,4 @@
-import type { MembersParams } from "../api/types.js";
+import type { InvitationsParams, MembersParams } from "../api/types.js";
 
 /**
  * Namespaced TanStack Query keys (frontend-standard §2 — "ключи неймспейснуты").
@@ -18,6 +18,21 @@ export const workspacesQueryKeys: {
     workspaceId: string,
     params: MembersParams
   ): readonly ["workspaces", "members", string, MembersParams];
+  invitations(workspaceId: string): readonly ["workspaces", "invitations", string];
+  invitationsPage(
+    workspaceId: string,
+    params: InvitationsParams
+  ): readonly ["workspaces", "invitations", string, InvitationsParams];
+  invitationsInfinite(
+    workspaceId: string,
+    filters: InvitationsParams
+  ): readonly [
+    "workspaces",
+    "invitations",
+    string,
+    "infinite",
+    InvitationsParams,
+  ];
   roles(): readonly ["workspaces", "roles"];
   invitationPreview(
     token: string
@@ -30,6 +45,25 @@ export const workspacesQueryKeys: {
   // invalidating `members(workspaceId)` (mutations.ts) drops every page.
   members: (workspaceId) => [ROOT, "members", workspaceId],
   membersPage: (workspaceId, params) => [ROOT, "members", workspaceId, params],
+  // Same prefix trick as `members`: the bare 3-tuple invalidates every page
+  // (and the infinite list, which keys on it) after a revoke / resend.
+  invitations: (workspaceId) => [ROOT, "invitations", workspaceId],
+  invitationsPage: (workspaceId, params) => [
+    ROOT,
+    "invitations",
+    workspaceId,
+    params,
+  ],
+  // The infinite list carries its own marker segment: its cached value is an
+  // `InfiniteData` envelope, not a page, so it must never collide with a
+  // single-page key that happens to hold the same filters.
+  invitationsInfinite: (workspaceId, filters) => [
+    ROOT,
+    "invitations",
+    workspaceId,
+    "infinite",
+    filters,
+  ],
   roles: () => [ROOT, "roles"],
   // NOTE: the key carries the invite TOKEN (a secret). Core's query persist
   // scope is per-user and the preview response is already public-by-design

package/src/model/stepUp.ts

@@ -0,0 +1,96 @@
+/**
+ * Step-up ahead of the button, not behind it (org-program §A3).
+ *
+ * Some workspace operations are declared **high**: the backend gates them
+ * with `stapel_core`'s `@requires_verification(scope="sensitive")` on top of
+ * the capability check, so an ambient cookie is never enough. A client that
+ * only learns this from the 403 shows the admin a button, a spinner and a
+ * refusal; this module lets it know BEFORE the click.
+ *
+ * Two things travel from the backend, and they are not the same thing:
+ *
+ * 1. **A step-up CHALLENGE** — `verification.challenge_id` is present. This
+ *    one nobody has to handle here: `@stapel/core`'s client intercepts it,
+ *    hands it to the app's verification controller (auth-react's factor
+ *    machines) and replays the original request with
+ *    `X-Verification-Token`. It is a detour, not a failure.
+ * 2. **An ENROLLMENT demand** — `verification.enroll === true` and there is
+ *    NO challenge id, because the user holds no factor that could be
+ *    challenged. Core deliberately does not intercept this one (there is
+ *    nothing to drive), so it surfaces as a plain 403 and the app must send
+ *    the user to factor enrollment first. {@link readVerificationEnrollment}
+ *    is how a hook says "this is that, and these are the factors".
+ *
+ * KEEP IN SYNC with stapel-workspaces `capabilities.BUILTIN_CAPABILITY_LEVELS`
+ * — a PORT for the same reason `capabilityMatches` is one: `GET /roles`
+ * publishes each role's capabilities but not their levels, so the level map
+ * cannot be read off the wire. A deployment may raise further capabilities via
+ * `STAPEL_WORKSPACES["CAPABILITY_LEVELS"]`; those are additive, so treating an
+ * unlisted capability as `standard` can only ever under-promise (the backend
+ * still challenges, and core still drives it).
+ */
+import { isStapelApiError } from "@stapel/core";
+
+/** The verification scope every `high` workspace capability is gated under. */
+export const SENSITIVE_SCOPE = "sensitive";
+
+/** Step-up level of a capability. */
+export type CapabilityLevel = "standard" | "high";
+
+/** PORT of `BUILTIN_CAPABILITY_LEVELS` — everything unlisted is `standard`. */
+export const BUILTIN_CAPABILITY_LEVELS: Readonly<Record<string, "high">> = {
+  "members.provision": "high",
+  "members.password.reset": "high",
+  "workspace.security.manage": "high",
+};
+
+/** The declared step-up level of one capability string. */
+export function capabilityLevel(capability: string): CapabilityLevel {
+  return BUILTIN_CAPABILITY_LEVELS[capability] ?? "standard";
+}
+
+/**
+ * The 403 ENROLLMENT envelope: the caller must first enroll one of `factors`
+ * — there is no challenge to complete, so core cannot drive it.
+ */
+export interface VerificationEnrollment {
+  /** What the demand protects — `"sensitive"` for every `high` capability. */
+  readonly scope: string;
+  /** Interchangeable factors, any ONE of which unblocks the operation. */
+  readonly factors: readonly string[];
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Read the enrollment demand out of a rejected request, or `null` when the
+ * error is anything else (including a step-up CHALLENGE, which carries a
+ * `challenge_id` and is core's business, not the consumer's).
+ */
+export function readVerificationEnrollment(
+  error: unknown
+): VerificationEnrollment | null {
+  // Both dialects, narrowed through the imported predicate (never through a
+  // shape this call site invented): the typed error carries the parsed body,
+  // a rethrown raw envelope IS the body.
+  const body = asRecord(isStapelApiError(error) ? error.body : error);
+  if (body === null) return null;
+  const verification = asRecord(body["verification"]);
+  if (verification === null) return null;
+  if (verification["enroll"] !== true) return null;
+  if (typeof verification["challenge_id"] === "string") return null;
+  const factors = verification["factors"];
+  return {
+    scope:
+      typeof verification["scope"] === "string"
+        ? verification["scope"]
+        : SENSITIVE_SCOPE,
+    factors: Array.isArray(factors)
+      ? factors.filter((f): f is string => typeof f === "string")
+      : [],
+  };
+}