@stapel/workspaces-react 0.17.0 → 0.19.1

package/src/api/generated/schema.ts

@@ -10,26 +10,26 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Turns an unaskable plan ceiling into 503 for the whole view.
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
-         *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *     Mixed in rather than written as an ``except`` at each call site because
+         *     the seam is consulted from views AND from inside ``services`` under the
+         *     workspace lock, and the set of call sites grows: a view that gains a
+         *     method later inherits the mapping instead of re-deriving it. The 402
+         *     denials stay per-call-site — those carry a limit the screen renders.
          *
          *     **Permissions:** `IsAuthenticated`
          */
         get: operations["workspaces_api_v1_retrieve"];
         put?: never;
         /**
-         * @description Overridable serializer seams for API views.
-         *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         * @description Turns an unaskable plan ceiling into 503 for the whole view.
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *     Mixed in rather than written as an ``except`` at each call site because
+         *     the seam is consulted from views AND from inside ``services`` under the
+         *     workspace lock, and the set of call sites grows: a view that gains a
+         *     method later inherits the mapping instead of re-deriving it. The 402
+         *     denials stay per-call-site — those carry a limit the screen renders.
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -48,13 +48,21 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Overridable request/response serializer seam for an API view.
+         *
+         *     Declare the classes as attributes, read them through the getters::
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         *         class WalletView(SerializerSeamMixin, APIView):
+         *             response_serializer_class = WalletResponseSerializer
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *             def get(self, request):
+         *                 response_cls = self.get_response_serializer_class()
+         *                 return StapelResponse(response_cls(wallet_to_dto(...)))
+         *
+         *     A host project swaps either direction by subclassing and setting the
+         *     attribute, or overrides the getter for a per-request decision — no HTTP
+         *     method body is ever copied. ``None`` means the direction carries no
+         *     serializer (raw ``request.FILES``, an empty 204 body).
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -62,13 +70,13 @@ export interface paths {
         put?: never;
         post?: never;
         /**
-         * @description Overridable serializer seams for API views.
-         *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         * @description End a workspace — the transition itself lives in the service.
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *     The view's whole job here is authority (owner, and only owner) and
+         *     turning the service's typed refusal back into the keyed 409 the
+         *     frontend routes on. The write, the event and the audit line are one
+         *     indivisible act in ``services.delete_workspace``, because a second
+         *     door into this transition is a second chance to forget the record.
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -76,13 +84,21 @@ export interface paths {
         options?: never;
         head?: never;
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Overridable request/response serializer seam for an API view.
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         *     Declare the classes as attributes, read them through the getters::
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *         class WalletView(SerializerSeamMixin, APIView):
+         *             response_serializer_class = WalletResponseSerializer
+         *
+         *             def get(self, request):
+         *                 response_cls = self.get_response_serializer_class()
+         *                 return StapelResponse(response_cls(wallet_to_dto(...)))
+         *
+         *     A host project swaps either direction by subclassing and setting the
+         *     attribute, or overrides the getter for a per-request decision — no HTTP
+         *     method body is ever copied. ``None`` means the direction carries no
+         *     serializer (raw ``request.FILES``, an empty 204 body).
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -292,13 +308,21 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Overridable request/response serializer seam for an API view.
+         *
+         *     Declare the classes as attributes, read them through the getters::
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         *         class WalletView(SerializerSeamMixin, APIView):
+         *             response_serializer_class = WalletResponseSerializer
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *             def get(self, request):
+         *                 response_cls = self.get_response_serializer_class()
+         *                 return StapelResponse(response_cls(wallet_to_dto(...)))
+         *
+         *     A host project swaps either direction by subclassing and setting the
+         *     attribute, or overrides the getter for a per-request decision — no HTTP
+         *     method body is ever copied. ``None`` means the direction carries no
+         *     serializer (raw ``request.FILES``, an empty 204 body).
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -322,13 +346,21 @@ export interface paths {
         put?: never;
         post?: never;
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Overridable request/response serializer seam for an API view.
+         *
+         *     Declare the classes as attributes, read them through the getters::
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         *         class WalletView(SerializerSeamMixin, APIView):
+         *             response_serializer_class = WalletResponseSerializer
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *             def get(self, request):
+         *                 response_cls = self.get_response_serializer_class()
+         *                 return StapelResponse(response_cls(wallet_to_dto(...)))
+         *
+         *     A host project swaps either direction by subclassing and setting the
+         *     attribute, or overrides the getter for a per-request decision — no HTTP
+         *     method body is ever copied. ``None`` means the direction carries no
+         *     serializer (raw ``request.FILES``, an empty 204 body).
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -336,13 +368,21 @@ export interface paths {
         options?: never;
         head?: never;
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Overridable request/response serializer seam for an API view.
+         *
+         *     Declare the classes as attributes, read them through the getters::
+         *
+         *         class WalletView(SerializerSeamMixin, APIView):
+         *             response_serializer_class = WalletResponseSerializer
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         *             def get(self, request):
+         *                 response_cls = self.get_response_serializer_class()
+         *                 return StapelResponse(response_cls(wallet_to_dto(...)))
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *     A host project swaps either direction by subclassing and setting the
+         *     attribute, or overrides the getter for a per-request decision — no HTTP
+         *     method body is ever copied. ``None`` means the direction carries no
+         *     serializer (raw ``request.FILES``, an empty 204 body).
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -480,13 +520,13 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * @description Overridable serializer seams for API views.
+         * @description Turns an unaskable plan ceiling into 503 for the whole view.
          *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
-         *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *     Mixed in rather than written as an ``except`` at each call site because
+         *     the seam is consulted from views AND from inside ``services`` under the
+         *     workspace lock, and the set of call sites grows: a view that gains a
+         *     method later inherits the mapping instead of re-deriving it. The 402
+         *     denials stay per-call-site — those carry a limit the screen renders.
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -520,7 +560,8 @@ export interface paths {
          *     Gate stack, in order: HIGH step-up (``@requires_verification``, scope
          *     ``sensitive`` — the same store as admin step-up) → capability
          *     ``members.provision`` (403) → entitlement ``workspaces.provision_user``
-         *     (402; degrades to allow without billing) → optional per-user debit
+         *     (402; an unreachable billing answers 503, not allow) → optional
+         *     per-user debit
          *     (``STAPEL_WORKSPACES["PROVISION_USER_CREDITS"]`` > 0).
          *
          *     Credentials: a synthetic account normally has no email — when the
@@ -653,6 +694,11 @@ export interface paths {
          *     NOT consumed here: accept stays a separate, deliberate step after
          *     setup. Neither the invite token nor the grant token is ever logged.
          *
+         *     ONE live grant at a time (WORK-03): while the previous grant is inside
+         *     its TTL this answers 429 ``error.429.invitation_grant_pending`` with a
+         *     ``Retry-After``, so a leaked invite link cannot be replayed into an
+         *     endless supply of sign-in credentials for the invited mailbox.
+         *
          *     **Permissions:** `AllowAny`
          */
         post: operations["workspaces_api_v1_invitations_claim_create"];
@@ -674,11 +720,36 @@ export interface paths {
         /**
          * @description Decline an invitation — the invitee's terminal "no" (spec §B2).
          *
-         *     Authenticated + email-match, exactly like accept: only the invited
-         *     account may resolve the invitation, in either direction. Decline ≠
-         *     revoke — both states stay distinguishable in the preview ``status``.
+         *     AllowAny, on the token, exactly like preview and claim — and this is a
+         *     CHANGE from the original authenticated-only rule, made because that rule
+         *     made the common "no" impossible to say.
+         *
+         *     Saying no used to require an account. The invitee who has none is the
+         *     majority case on this path (that is why ``claim`` exists at all), so
+         *     declining meant first creating the very account the person was declining
+         *     to create: the flow asked for the commitment before the decision, and
+         *     the refusal left a live, empty account behind it. Verified on the stand.
+         *
+         *     The token is the proof, and it is the same proof the module already
+         *     accepts elsewhere for strictly more: ``claim`` takes this token from an
+         *     anonymous caller and mints a LOGIN GRANT for the invited mailbox.
+         *     Anything a token holder could do by declining, they could already do —
+         *     and more — by claiming. What the token cannot do is act as somebody
+         *     else: a request that arrives WITH a session naming an address must still
+         *     be the invited address, so a signed-in person cannot resolve an
+         *     invitation belonging to someone else. That check is unchanged.
+         *
+         *     A session with no address at all (a guest session — this product mints
+         *     them at meeting doors) is treated as the anonymous case rather than as a
+         *     mismatched account: it names nobody, so it can neither prove nor
+         *     disprove ownership, and the token stands on its own. Before this it was
+         *     refused outright by ``ANONYMOUS_DENIED``, which is how a guest who was
+         *     also an invitee could not decline at all.
+         *
+         *     Decline ≠ revoke — both states stay distinguishable in the preview
+         *     ``status``. Throttled and token-never-logged like its AllowAny siblings.
          *
-         *     **Permissions:** `IsAuthenticated`
+         *     **Permissions:** `AllowAny`
          */
         post: operations["workspaces_api_v1_invitations_decline_create"];
         delete?: never;
@@ -697,13 +768,13 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * @description Overridable serializer seams for API views.
-         *
-         *     Subclasses (or downstream projects) can swap the request/response
-         *     serializers without copying method bodies:
+         * @description Turns an unaskable plan ceiling into 503 for the whole view.
          *
-         *         class MyWorkspaceDetailView(WorkspaceDetailView):
-         *             response_serializer_class = MyWorkspaceResponseSerializer
+         *     Mixed in rather than written as an ``except`` at each call site because
+         *     the seam is consulted from views AND from inside ``services`` under the
+         *     workspace lock, and the set of call sites grows: a view that gains a
+         *     method later inherits the mapping instead of re-deriving it. The 402
+         *     denials stay per-call-site — those carry a limit the screen renders.
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -999,6 +1070,46 @@ export interface components {
              */
             last_sent_at?: string | null;
         };
+        /** @description How far the workspace's require_mfa policy has actually got. */
+        MFAEnforcementStatus: {
+            /**
+             * @description pending / enforcing / enforced / failed. Only "enforced" means every active member's second factor has been confirmed — a settings flag saying require_mfa=true says somebody asked for it, not that it holds
+             * @example enforcing
+             */
+            state: string;
+            /**
+             * @description How many sweeps have run since the policy was switched on
+             * @example 3
+             */
+            attempts?: number;
+            /**
+             * @description Members auth answered about in the last sweep
+             * @example 12
+             */
+            checked_members?: number;
+            /**
+             * @description Of those, members with no strong factor — suspended with reason no_mfa
+             * @example 2
+             */
+            noncompliant_members?: number;
+            /**
+             * @description Active members whose factor nobody has confirmed yet. They are NOT admitted while the policy is on; this is the number an administrator has to get to zero
+             * @example 1
+             */
+            unverified_members?: number;
+            /**
+             * @description ISO 8601 time of the last sweep; null before the first
+             * @example 2026-08-11T10:00:00Z
+             */
+            last_attempt_at?: string | null;
+            /** @description ISO 8601 time coverage last became complete; null while it is not */
+            completed_at?: string | null;
+            /**
+             * @description What auth answered when the last sweep failed, verbatim; empty otherwise. Never credential material
+             * @example FunctionCallError: mfa_status timed out
+             */
+            last_error?: string;
+        };
         /** @description Invite payload. */
         MemberInviteRequest: {
             /**
@@ -1109,6 +1220,13 @@ export interface components {
              * @example Ada Lovelace
              */
             display_name?: string | null;
+            /**
+             * @description Whether this member was PROVEN to hold a strong second factor — true, false, or null for "nobody has asked yet". Under a require_mfa policy the null is what an administrator acts on: those members are not admitted until the answer arrives
+             * @example true
+             */
+            mfa_compliant?: boolean | null;
+            /** @description Whether this row IS the caller. Server-derived — the client is never asked to compare ids it may not have. Always false on the service-to-service membership read, where the caller is a service and not a member of anything */
+            is_self?: boolean;
         };
         PaginatedAuditEventResponseList: {
             items: components["schemas"]["AuditEventResponse"][];
@@ -1396,6 +1514,15 @@ export interface components {
              * @example Victor P.
              */
             owner_display_name?: string;
+            /** @description State of the security.require_mfa policy — present on the single-workspace responses (GET/PATCH detail) when the policy is on, null otherwise. The settings block says what was asked for; this says what actually holds, so an administrator who switched MFA on is not told "done" while half the organization was never checked */
+            mfa_enforcement?: components["schemas"]["MFAEnforcementStatus"] | null;
+            /** @description Whether THIS caller may delete THIS workspace right now. The ANSWER, not the inputs: a client deriving it from my_role alone draws a delete button on the instance's default workspace and on a personal workspace the next sign-in re-mints — both of which the endpoint refuses, which is the "button that leads to a refusal" defect. Same shape and same reason as can_create_workspace on the list response */
+            can_delete?: boolean;
+            /**
+             * @description The error code the DELETE would return, or "" when can_delete is true. The CODE rather than a sentence, so the client renders the refusal in the caller's own language through the error map it already ships. Server verdict and screen explanation are ONE evaluation (services.deletion_block_reason), so a screen cannot promise what the endpoint denies
+             * @example error.409.workspace_is_instance_default
+             */
+            delete_blocked_reason?: string;
         };
     };
     responses: never;

package/src/default/ActiveWorkspace.tsx

@@ -0,0 +1,97 @@
+/**
+ * "Which workspace is this screen about" — the seam between the NAV contract
+ * and the four workspace-scoped admin screens.
+ *
+ * The nav contract routes a screen; it does not hand it an ambient scope, and
+ * the active workspace is not a path segment of a settings URL — it is
+ * RUNTIME state, the same state the container writes when a person switches
+ * (`WorkspaceSelection.switchTo`). So a screen declared in nav takes NO
+ * `workspaceId` from the route and reads it from
+ * {@link useOptionalWorkspaceSelection} instead; a host that mounts the same
+ * component itself keeps passing `workspaceId` explicitly and never touches
+ * the selection at all.
+ *
+ * The `Optional` accessor is load-bearing. `useWorkspaceSelection()` throws
+ * outside its provider, which is right for application code and wrong for a
+ * screen the shell mounts from a manifest: a shell that has not wired the
+ * provider would render a white page with an error in the console. Here the
+ * three answers a person can actually get are drawn instead:
+ *
+ *  - the list is still loading / failed → the substrate's own arms (a
+ *    skeleton, and the failure WITH a retry — never "you have no workspaces"),
+ *  - the person belongs to none → "you are not in a workspace yet",
+ *  - there is no selection at all (no provider, or nothing resolved) →
+ *    "choose a workspace".
+ *
+ * None of them is blank, and none of them claims something the client does
+ * not know.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { useT } from "@stapel/core";
+import { EmptyState, LoadBoundary } from "@stapel/tokens-antd/skin";
+import { useOptionalWorkspaceSelection } from "../model/selection.js";
+import { WORKSPACES_I18N_KEYS } from "../i18n/keys.js";
+
+export interface ActiveWorkspaceBoundaryProps {
+  /** The workspace the HOST named. Given, the selection is never consulted. */
+  readonly workspaceId?: string | undefined;
+  /** Rendered once a workspace id is known. */
+  readonly children: (workspaceId: string) => ReactNode;
+  /** Test id of the chooser / empty arms (the ready arm has no wrapper). */
+  readonly testId: string;
+}
+
+/**
+ * Resolve the workspace this screen is about, or draw the reason it cannot be
+ * resolved. Renders `children(workspaceId)` unchanged once there is one.
+ */
+export function ActiveWorkspaceBoundary(
+  props: ActiveWorkspaceBoundaryProps
+): ReactElement {
+  const t = useT();
+  // Unconditional, as a hook must be: reading the context is cheap and it
+  // returns null outside a provider rather than throwing.
+  const selection = useOptionalWorkspaceSelection();
+
+  if (props.workspaceId !== undefined) {
+    return <>{props.children(props.workspaceId)}</>;
+  }
+
+  const chooser = (
+    <EmptyState
+      title={t(WORKSPACES_I18N_KEYS.activeChooseTitle)}
+      hint={t(WORKSPACES_I18N_KEYS.activeChooseHint)}
+      testId={`${props.testId}-choose`}
+    />
+  );
+
+  if (selection === null) return chooser;
+
+  return (
+    <LoadBoundary
+      state={selection.state}
+      testId={props.testId}
+      onRetry={() => {
+        void selection.refetch();
+      }}
+    >
+      {(workspaces) => {
+        if (selection.current !== null) {
+          return <>{props.children(selection.current.id)}</>;
+        }
+        // The list arrived and the chain still answered nobody: either the
+        // person belongs to no workspace (a different sentence from "pick
+        // one"), or a host is driving the URL layer at something unresolved.
+        return workspaces.length === 0 ? (
+          <EmptyState
+            title={t(WORKSPACES_I18N_KEYS.activeNoneTitle)}
+            hint={t(WORKSPACES_I18N_KEYS.activeNoneHint)}
+            testId={`${props.testId}-none`}
+          />
+        ) : (
+          chooser
+        );
+      }}
+    </LoadBoundary>
+  );
+}