diff --git a/packages/react/src/plugins/oauth-admin-block.test.ts b/packages/react/src/plugins/oauth-admin-block.test.ts
new file mode 100644
index 0000000000..103aeda12d
--- /dev/null
+++ b/packages/react/src/plugins/oauth-admin-block.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Exit from "effect/Exit";
+import { OAuthStartError } from "@executor-js/sdk/shared";
+
+import { adminBlockFrom, adminBlockFromExit, adminBlockReference } from "./oauth-admin-block";
+
+// The claim these tests defend is a product claim, not a parsing one: a console
+// may only withdraw the interactive route when the identity provider actually
+// refused under policy. Reading it wrong in one direction strands a user with a
+// recoverable error and no retry; in the other, it walks them around the exact
+// control the enterprise just exercised.
+
+const denial = new OAuthStartError({
+ message: "Your organization does not permit this server.",
+ blockedByAdmin: true,
+ oauthErrorCode: "invalid_target",
+});
+
+describe("adminBlockFrom", () => {
+ it("reads the verdict off the typed field", () => {
+ expect(adminBlockFrom(denial)).toEqual({
+ message: "Your organization does not permit this server.",
+ oauthErrorCode: "invalid_target",
+ });
+ });
+
+ it("carries a null reference when the provider returned no code", () => {
+ expect(
+ adminBlockFrom(new OAuthStartError({ message: "Refused.", blockedByAdmin: true }))
+ ?.oauthErrorCode,
+ ).toBeNull();
+ });
+
+ it("leaves an ordinary start failure alone", () => {
+ // No verdict means the interactive route stays open — an expired app, a
+ // bad endpoint, a network fault are all things a retry can fix.
+ expect(
+ adminBlockFrom(new OAuthStartError({ message: "Failed to reach the token endpoint." })),
+ ).toBeNull();
+ });
+
+ it("does not treat an explicitly-false verdict as a denial", () => {
+ expect(
+ adminBlockFrom(new OAuthStartError({ message: "Refused.", blockedByAdmin: false })),
+ ).toBeNull();
+ });
+
+ it("never infers a denial from the wording of a message", () => {
+ // The whole reason the field exists. A message that says the words is
+ // still not a verdict, and a console that matched on text would start
+ // withdrawing the retry for failures the user could have recovered from.
+ expect(
+ adminBlockFrom(
+ new OAuthStartError({ message: "blocked by admin: your organization declined" }),
+ ),
+ ).toBeNull();
+ });
+
+ it("finds the verdict through the popup flow's one level of wrapping", () => {
+ // `openAuthorization` rejects with its own error carrying the server's
+ // failure as `cause`; the verdict has to survive that hop or the modal
+ // sees only a sentence.
+ expect(adminBlockFrom({ message: "Failed to start sign-in", cause: denial })).toEqual({
+ message: "Your organization does not permit this server.",
+ oauthErrorCode: "invalid_target",
+ });
+ });
+
+ it("does not go hunting down a cause chain", () => {
+ // One level is the contract. A chain is not a search space: something
+ // deeper is not this connect's verdict.
+ expect(adminBlockFrom({ cause: { cause: denial } })).toBeNull();
+ });
+
+ it("reads nothing out of values that are not start failures", () => {
+ expect(adminBlockFrom(null)).toBeNull();
+ expect(adminBlockFrom("blocked")).toBeNull();
+ expect(adminBlockFrom({ blockedByAdmin: true })).toBeNull();
+ });
+});
+
+describe("adminBlockFromExit", () => {
+ it("reads the verdict out of a failed exit", () => {
+ expect(adminBlockFromExit(Exit.fail(denial))?.oauthErrorCode).toBe("invalid_target");
+ });
+
+ it("has no verdict for a successful exit", () => {
+ expect(adminBlockFromExit(Exit.succeed({ status: "connected" }))).toBeNull();
+ });
+});
+
+describe("adminBlockReference", () => {
+ it("quotes the provider's own code so a member can trace it", () => {
+ expect(adminBlockReference({ message: "…", oauthErrorCode: "invalid_target" })).toBe(
+ "Reference: invalid_target",
+ );
+ });
+
+ it("shows no reference line when there is no code to show", () => {
+ expect(adminBlockReference({ message: "…", oauthErrorCode: null })).toBeNull();
+ });
+});
diff --git a/packages/react/src/plugins/oauth-admin-block.ts b/packages/react/src/plugins/oauth-admin-block.ts
new file mode 100644
index 0000000000..7be23de320
--- /dev/null
+++ b/packages/react/src/plugins/oauth-admin-block.ts
@@ -0,0 +1,75 @@
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { OAuthStartError } from "@executor-js/sdk/shared";
+
+// ---------------------------------------------------------------------------
+// Blocked by administrator — reading an enterprise policy denial as STRUCTURE.
+//
+// When an enterprise identity provider refuses to mint an ID-JAG, the failure
+// is an administrator's decision, not a credential problem. `OAuthStartError`
+// says so in a typed field (`blockedByAdmin`) precisely so a console never has
+// to read the sentence: matching on message text would silently start passing
+// or failing whenever the wording changed, and the consequence of getting it
+// wrong is offering the interactive per-server flow — which would route the
+// user straight around the control the enterprise just exercised.
+//
+// So: this module decodes the field, and NOTHING here inspects `message`
+// except to display it.
+// ---------------------------------------------------------------------------
+
+/** An enterprise identity provider declined this connect under administrator
+ * policy. Terminal by construction: there is no retry and no alternative
+ * route to offer, only the decision and a code support can trace. */
+export interface OAuthAdminBlock {
+ /** The failure's own message, shown verbatim. */
+ readonly message: string;
+ /** The identity provider's RFC 6749 §5.2 code (`unauthorized_client`,
+ * `invalid_target`, …), when it returned one. Null otherwise. */
+ readonly oauthErrorCode: string | null;
+}
+
+const decodeStartError = Schema.decodeUnknownOption(OAuthStartError);
+
+/** One level of wrapping: the popup flow wraps a start failure in its own
+ * tagged error before it reaches a renderer, and the verdict must survive
+ * that hop. Exactly one level — a `cause` chain is not a search space. */
+const decodeWrapped = Schema.decodeUnknownOption(Schema.Struct({ cause: Schema.Unknown }));
+
+const directAdminBlock = (error: unknown): OAuthAdminBlock | null =>
+ Option.match(decodeStartError(error), {
+ onNone: () => null,
+ onSome: (start) =>
+ start.blockedByAdmin === true
+ ? { message: start.message, oauthErrorCode: start.oauthErrorCode ?? null }
+ : null,
+ });
+
+/** The administrator verdict carried by a failed `oauth.start`, or null when
+ * the failure is anything else — including every other OAuth start failure,
+ * which leaves the interactive route open. */
+export const adminBlockFrom = (error: unknown): OAuthAdminBlock | null =>
+ directAdminBlock(error) ??
+ Option.match(decodeWrapped(error), {
+ onNone: () => null,
+ onSome: (wrapper) => directAdminBlock(wrapper.cause),
+ });
+
+/** `adminBlockFrom` over an `Exit`, for the mutation call sites that hold one. */
+export const adminBlockFromExit = (exit: Exit.Exit): OAuthAdminBlock | null =>
+ Option.match(Exit.findErrorOption(exit), {
+ onNone: () => null,
+ onSome: adminBlockFrom,
+ });
+
+/** What the user is told. Sentence case per the design system's voice rules:
+ * what happened, then what to do next — and the next step is a person, not a
+ * button, because no action in this console can change the verdict. */
+export const ADMIN_BLOCK_TITLE = "Blocked by your organization";
+export const ADMIN_BLOCK_NEXT_STEP =
+ "Ask an administrator to allow this server at your identity provider.";
+
+/** The support-traceable reference line, or null when the provider returned no
+ * code. Mono metadata, per the design system. */
+export const adminBlockReference = (block: OAuthAdminBlock): string | null =>
+ block.oauthErrorCode === null ? null : `Reference: ${block.oauthErrorCode}`;
diff --git a/packages/react/src/plugins/oauth-sign-in.tsx b/packages/react/src/plugins/oauth-sign-in.tsx
index f46d6378e5..5febaeaf95 100644
--- a/packages/react/src/plugins/oauth-sign-in.tsx
+++ b/packages/react/src/plugins/oauth-sign-in.tsx
@@ -16,6 +16,7 @@ import {
} from "../api/oauth-popup";
import { connectionWriteKeys } from "../api/reactivity-keys";
import { getActiveOrgSlug } from "../api/server-connection";
+import { adminBlockFromExit, type OAuthAdminBlock } from "./oauth-admin-block";
export type DesktopBridge = {
readonly openExternal: (url: string) => Promise;
@@ -193,6 +194,10 @@ export function useOAuthPopupFlow<
const blockedMessage = popupBlockedMessage ?? POPUP_BLOCKED_MESSAGE;
const [busy, setBusy] = useState(false);
const [error, setError] = useState(null);
+ // The enterprise verdict, held apart from `error` on purpose: a renderer must
+ // be able to tell "this failed, try again" from "your organization decided
+ // this" WITHOUT reading either string.
+ const [adminBlock, setAdminBlock] = useState(null);
const cleanupRef = useRef<(() => void) | null>(null);
const sessionRef = useRef<{ readonly state: string } | null>(null);
// A window reserved on the click but not yet handed to a flow owns nothing
@@ -274,6 +279,7 @@ export function useOAuthPopupFlow<
}
setBusy(true);
setError(null);
+ setAdminBlock(null);
// Desktop hosts open the auth URL in the user's real browser, so they
// reserve no in-page window and rely on the polling channel for the
// result.
@@ -294,6 +300,12 @@ export function useOAuthPopupFlow<
);
if (Exit.isFailure(startExit)) {
const message = messageFromExit(startExit, startErrorMessage ?? "Failed to start sign-in");
+ // Read the enterprise verdict off the failure BEFORE it is reduced to a
+ // string. Present means the identity provider refused under
+ // administrator policy, and this flow ends here: the popup closes and
+ // no retry is offered, because retrying is the route the enterprise
+ // just closed.
+ const blocked = adminBlockFromExit(startExit);
reportHandledError(startExit.cause, {
surface: "oauth",
action: "start",
@@ -302,6 +314,7 @@ export function useOAuthPopupFlow<
});
reservedPopup?.popup.close();
setBusy(false);
+ setAdminBlock(blocked);
setError(message);
input.onError?.(message);
return;
@@ -455,29 +468,37 @@ export function useOAuthPopupFlow<
newConnection: input.payload.newConnection,
redirectUri: input.payload.redirectUri ?? oauthCallbackUrl(callbackPath),
},
- }).then((exit) =>
- Exit.isSuccess(exit)
- ? // The redirect branch carries `authorizationUrl` + `state`; the
- // inline "connected" (client_credentials) branch has no URL to
- // open and no redirect, so `state` is intentionally empty — it
- // is never read for an already-minted connection.
- exit.value.status === "redirect"
+ }).then((exit) => {
+ if (Exit.isSuccess(exit)) {
+ // The redirect branch carries `authorizationUrl` + `state`; the
+ // inline "connected" (client_credentials / enterprise-managed)
+ // branch has no URL to open and no redirect, so `state` is
+ // intentionally empty — it is never read for an already-minted
+ // connection.
+ return exit.value.status === "redirect"
? { state: exit.value.state, authorizationUrl: exit.value.authorizationUrl }
- : { state: "", authorizationUrl: null }
- : Effect.runPromise(
- Effect.fail({
- message: messageFromExit(exit, startErrorMessage ?? "Failed to start sign-in"),
- }),
- ),
- ),
+ : { state: "", authorizationUrl: null };
+ }
+ // Reject with the server's OWN typed failure, cause and all — not
+ // with a message extracted from it. `openAuthorization` wraps this
+ // as the `cause` of its start error, and that is where the
+ // enterprise verdict (`blockedByAdmin`) is read from; flattening it
+ // to a string here would leave the console with only a sentence to
+ // branch on, which is exactly what it must not decide from.
+ return Effect.runPromise(Effect.failCause(exit.cause));
+ }),
});
},
- [callbackPath, doStartOAuth, openAuthorization, startErrorMessage],
+ [callbackPath, doStartOAuth, openAuthorization],
);
return {
busy,
error,
+ /** The enterprise policy denial behind `error`, when there was one. A
+ * renderer branches on this — never on `error`'s wording — and must not
+ * offer a retry while it is set. */
+ adminBlock,
setError,
start,
openAuthorization,