@stapel/workspaces-react 0.6.0 → 0.8.0

package/src/index.ts

@@ -25,6 +25,12 @@ export type {
   FlowError,
 } from "@stapel/core";
 export { toFlowError } from "./flows/errors.js";
+export { createInviteAcceptFlow } from "./flows/inviteAcceptFlow.js";
+export type {
+  InviteAcceptFlow as InviteAcceptFlowController,
+  InviteAcceptFlowDeps,
+  InviteAcceptState,
+} from "./flows/inviteAcceptFlow.js";
 export { WORKSPACES_FLOWS, flowEndpoints } from "./flows/registry.js";
 export type {
   WorkspacesFlowId,
@@ -51,7 +57,28 @@ export {
   useWorkspaces,
   useWorkspace,
   useMembers,
+  useInvitations,
+  useInfiniteInvitations,
+  useRoles,
+  useInvitationPreview,
+  useCapabilities,
+  useCapabilityGate,
 } 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) ──────────────────────────────────────────────────────
 export {
@@ -62,8 +89,17 @@ export {
   useUpdateMemberRole,
   useRemoveMember,
   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 {
@@ -78,7 +114,18 @@ export type {
   MemberInviteResult,
   MemberRoleUpdate,
   Invitation,
+  InvitationPage as InvitationListData,
+  InvitationsParams,
+  InvitationStatusFilter,
   InvitationAccept,
+  InvitationPreview,
+  InvitationClaim,
+  MemberPasswordReset,
+  MemberPasswordResetResult,
+  ProvisionedUserPolicy,
+  WorkspaceSecuritySettings,
+  RoleInfo,
+  RoleList,
   WorkspaceRole,
   WorkspaceKind,
 } from "./api/types.js";
@@ -91,6 +138,12 @@ export { Members } from "./headless/Members.js";
 export type { MembersBag } from "./headless/Members.js";
 export { AcceptInvitation } from "./headless/AcceptInvitation.js";
 export type { AcceptInvitationBag } from "./headless/AcceptInvitation.js";
+export { Can } from "./headless/Can.js";
+export type { CanBag } from "./headless/Can.js";
+export { RoleSelect } from "./headless/RoleSelect.js";
+export type { RoleSelectBag } from "./headless/RoleSelect.js";
+export { InviteAcceptFlow } from "./headless/InviteAcceptFlow.js";
+export type { InviteAcceptFlowBag } from "./headless/InviteAcceptFlow.js";
 
 // ── i18n ─────────────────────────────────────────────────────────────────────
 export {

package/src/model/capabilities.ts

@@ -0,0 +1,37 @@
+/**
+ * Client-side capability matcher (org-program §A1/§A2) — a PORT of
+ * stapel-workspaces' `capabilities.capability_matches` (which is itself
+ * mirrored by the consumer helper in `stapel_core.django.workspaces`).
+ * KEEP SEMANTICS IN SYNC with the backend: capability strings are namespaced
+ * `"<domain>.<action>"`, free-form for the client (`meetings.spotlight`,
+ * `records.view`, …); a granted string may be the exact capability, the
+ * global wildcard `"*"`, or a prefix wildcard like `"members.*"` (which
+ * matches `members.remove` AND deeper `members.role.change`).
+ *
+ * The client-side check is a UI convenience (hide/disable affordances) —
+ * NEVER an access decision: the backend re-checks every capability on every
+ * operation (`has_capability` in-service, `workspaces.check_capability`
+ * cross-service).
+ */
+
+/** Match one granted capability string against the requested one. */
+export function capabilityMatches(
+  capability: string,
+  granted: string
+): boolean {
+  if (granted === "*" || granted === capability) return true;
+  if (granted.endsWith(".*")) {
+    return capability.startsWith(granted.slice(0, -1));
+  }
+  return false;
+}
+
+/** True if any of `granted` (verbatim registry strings, wildcards included)
+ * matches `capability`. Empty/absent grants deny — deny-by-default. */
+export function hasCapability(
+  granted: readonly string[] | null | undefined,
+  capability: string
+): boolean {
+  if (!granted) return false;
+  return granted.some((g) => capabilityMatches(capability, g));
+}

package/src/model/emailMask.ts

@@ -0,0 +1,37 @@
+/**
+ * Email masking — a PORT of stapel-workspaces' `views._mask_email` (the
+ * function that produces `InvitationPreviewResponse.email_masked`). KEEP IN
+ * SYNC with the backend: first character of the local part and of the domain
+ * name survive, the TLD stays readable — `m***@e***.com`.
+ *
+ * Why the client re-implements it: the public invitation preview deliberately
+ * carries only the MASKED email (harvest-proof, org-program §B2), yet the
+ * §B4 flow must route "session & email match" vs "wrong account" BEFORE
+ * attempting the accept. Masking the signed-in account's own (fully known)
+ * email with the same algorithm and comparing the two masks is the exact
+ * decision the backend would make — without ever exposing the invitee's
+ * address. A mask collision (two addresses masking identically) merely shows
+ * the accept prompt; the backend's real email-match on accept remains the
+ * enforcement point.
+ */
+
+/** Mask an email exactly like the backend's invitation preview does. */
+export function maskEmail(email: string): string {
+  const at = email.indexOf("@");
+  const local = at === -1 ? email : email.slice(0, at);
+  const domain = at === -1 ? "" : email.slice(at + 1);
+  const dot = domain.lastIndexOf(".");
+  const maskedLocal = `${local.slice(0, 1) || "*"}***`;
+  if (dot !== -1) {
+    const domainName = domain.slice(0, dot);
+    const tld = domain.slice(dot + 1);
+    return `${maskedLocal}@${domainName.slice(0, 1) || "*"}***.${tld}`;
+  }
+  return `${maskedLocal}@${domain.slice(0, 1) || "*"}***`;
+}
+
+/** Whether `email`, masked by the backend's algorithm, equals `emailMasked`
+ * (case-insensitive on the email, as the backend matches `iexact`). */
+export function emailMatchesMask(email: string, emailMasked: string): boolean {
+  return maskEmail(email.trim().toLowerCase()) === emailMasked.toLowerCase();
+}

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,
-  WorkspaceRole,
+  WorkspaceSecuritySettings,
   WorkspaceUpdate,
 } from "../api/types.js";
 import { useWorkspacesApi } from "./context.js";
@@ -123,10 +127,14 @@ export function useInviteMembers(
   return useMutation(options);
 }
 
-/** The variable for {@link useUpdateMemberRole}: which member, which new role. */
+/** The variable for {@link useUpdateMemberRole}: which member, which new role.
+ * `role` is an open string since stapel-workspaces 0.6.0 (org-program §A1):
+ * the effective registry is settings-extensible, so any key of GET /roles is
+ * valid — the backend validates against the registry. {@link WorkspaceRole}
+ * still names the builtin four for literals. */
 export interface MemberRoleChange {
   readonly userId: string;
-  readonly role: WorkspaceRole;
+  readonly role: string;
 }
 
 /**
@@ -171,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`
@@ -186,10 +382,58 @@ export function useAcceptInvitation(): UseMutationResult<
   const queryClient = useQueryClient();
   const options: UseMutationOptions<Member, StapelApiError, InvitationAccept> = {
     mutationFn: (body) => api.acceptInvitation(body),
-    onSuccess: () => {
+    onSuccess: (_member, body) => {
       void queryClient.invalidateQueries({
         queryKey: workspacesQueryKeys.list(),
       });
+      // The preview's `status` moved pending → accepted.
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitationPreview(body.token),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/**
+ * Mint a login grant for a NOT-yet-registered invitee (POST
+ * /invitations/{token}/claim, AllowAny — org-program §B2/§B3). The variable
+ * is the invite token; the result carries the single-use `grant_token` to
+ * exchange at AUTH's `POST /grant/exchange/` (the auth-react api — this pair
+ * deliberately does not call it; see `InviteAcceptFlow`'s `onLoginGrant`
+ * seam). 409 `email_already_registered` → switch to login. The invitation is
+ * NOT consumed here. The grant token is a credential: never log it.
+ */
+export function useClaimInvitation(): UseMutationResult<
+  InvitationClaim,
+  StapelApiError,
+  string
+> {
+  const api = useWorkspacesApi();
+  const options: UseMutationOptions<InvitationClaim, StapelApiError, string> = {
+    mutationFn: (token) => api.claimInvitation(token),
+  };
+  return useMutation(options);
+}
+
+/**
+ * Decline an invitation (POST /invitations/{token}/decline, authenticated +
+ * email-match — org-program §B2). The variable is the invite token. Decline ≠
+ * revoke — the preview's `status` becomes `declined`.
+ */
+export function useDeclineInvitation(): UseMutationResult<
+  void,
+  StapelApiError,
+  string
+> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<void, StapelApiError, string> = {
+    mutationFn: (token) => api.declineInvitation(token),
+    onSuccess: (_result, token) => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitationPreview(token),
+      });
     },
   };
   return useMutation(options);

package/src/model/queries.ts

@@ -1,15 +1,26 @@
-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,
   Workspace,
   WorkspaceList,
 } from "../api/types.js";
 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;
@@ -77,3 +88,195 @@ export function useMembers(
     enabled: sessionReady && workspaceId !== null && workspaceId !== "",
   });
 }
+
+/**
+ * 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
+ * verbatim, rank-descending. Deployment-static data — role UI (RoleSelect)
+ * reads this instead of hardcoding the builtin four. Session-ready-gated like
+ * {@link useWorkspaces} (IsAuthenticated endpoint, mounts at screen top).
+ */
+export function useRoles(): UseQueryResult<
+  readonly RoleInfo[],
+  StapelApiError
+> {
+  const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
+  return useQuery({
+    queryKey: workspacesQueryKeys.roles(),
+    queryFn: async () => (await api.listRoles()).roles ?? [],
+    enabled: sessionReady,
+  });
+}
+
+/**
+ * Public invitation preview (GET /invitations/{token}, AllowAny — org-program
+ * §B2): what the `/invite/{token}` page renders BEFORE any auth decision.
+ * Deliberately NOT session-gated — the whole point is that the invitee may
+ * have no session at all; the token in the URL is the bearer secret.
+ */
+export function useInvitationPreview(
+  token: string | null
+): UseQueryResult<InvitationPreview, StapelApiError> {
+  const api = useWorkspacesApi();
+  return useQuery({
+    queryKey: workspacesQueryKeys.invitationPreview(token ?? ""),
+    queryFn: () => api.getInvitationPreview(token as string),
+    enabled: token !== null && token !== "",
+  });
+}
+
+/** What {@link useCapabilities} returns: the caller's granted capability
+ * strings in one workspace plus the wildcard-aware `can()` check. */
+export interface CapabilitiesResult {
+  /** Verbatim registry strings of the caller's role (wildcards included);
+   * empty while loading or when the caller is not a member. */
+  readonly capabilities: readonly string[];
+  /** Wildcard-aware check (`*` / `prefix.*` — the backend matcher, ported).
+   * UI convenience only: the backend re-checks on every operation. */
+  can(capability: string): boolean;
+  readonly isLoading: boolean;
+  readonly isError: boolean;
+  readonly error: StapelApiError | null;
+}
+
+/**
+ * The caller's capabilities in one workspace (org-program §A2): reads
+ * `my_capabilities` off the workspace detail (`WorkspaceResponse`, additive
+ * field since stapel-workspaces 0.6.0) and exposes the ported wildcard
+ * matcher. Deny-by-default: `can()` is false while loading, on error, or when
+ * the backend predates the field.
+ */
+export function useCapabilities(workspaceId: string | null): CapabilitiesResult {
+  const query = useWorkspace(workspaceId);
+  const capabilities = query.data?.my_capabilities ?? [];
+  return {
+    capabilities,
+    can: (capability) => hasCapability(capabilities, capability),
+    isLoading: query.isLoading,
+    isError: query.isError,
+    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,
+  };
+}