@stapel/workspaces-react 0.7.0 → 0.9.0

package/src/model/queries.ts

@@ -1,9 +1,16 @@
-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,
+  InstanceShape,
+  InvitationsParams,
   MemberPage,
   MembersParams,
   RoleInfo,
@@ -13,6 +20,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 +90,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
@@ -101,6 +174,35 @@ export function useRoles(): UseQueryResult<
   });
 }
 
+/**
+ * Deployment shape (GET /instance, unauthenticated).
+ *
+ * Answers the question a screen must ask BEFORE deciding what to show
+ * someone with no workspace: is this a closed deployment (`landing:
+ * "none"` — no workspace exists and none can be created) or a public cloud
+ * (`"personal"` — one exists and the screen can lead there)?
+ *
+ * Why a hook instead of a profile field: the reader is exactly the person
+ * who has no access — kicked out of their workspace, or having left it. So
+ * the request deliberately does NOT wait for a session, unlike {@link
+ * useRoles}: waiting would mean never answering the one person it exists for.
+ *
+ * The data is static per deployment — it only changes alongside the
+ * deployment itself, so the cache lives until page reload and is never
+ * refetched.
+ */
+export function useInstanceShape(): UseQueryResult<
+  InstanceShape,
+  StapelApiError
+> {
+  const api = useWorkspacesApi();
+  return useQuery({
+    queryKey: workspacesQueryKeys.instance(),
+    queryFn: () => api.getInstanceShape(),
+    staleTime: Infinity,
+  });
+}
+
 /**
  * Public invitation preview (GET /invitations/{token}, AllowAny — org-program
  * §B2): what the `/invite/{token}` page renders BEFORE any auth decision.
@@ -150,3 +252,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,7 +1,7 @@
-import type { MembersParams } from "../api/types.js";
+import type { InvitationsParams, MembersParams } from "../api/types.js";
 
 /**
- * Namespaced TanStack Query keys (frontend-standard §2 — "ключи неймспейснуты").
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
  * Everything under the `"workspaces"` root so a host can invalidate the whole
  * module or match a single resource. Persist scope is per-user via core's query
  * runtime (`setPersistUser`). Explicit tuple return types satisfy
@@ -18,7 +18,23 @@ 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"];
+  instance(): readonly ["workspaces", "instance"];
   invitationPreview(
     token: string
   ): readonly ["workspaces", "invitation-preview", string];
@@ -30,7 +46,27 @@ 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"],
+  instance: () => [ROOT, "instance"],
   // 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
   // (masked email only) — but hosts logging query keys should treat this one

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")
+      : [],
+  };
+}