// ---------------------------------------------------------------------------// Enterprise-Managed Authorization (EMA) — the client half.//// MCP "Enterprise-Managed Authorization" profiles// draft-ietf-oauth-identity-assertion-authz-grant-04 for the case where the MCP// client and the MCP server share an enterprise IdP. Instead of walking the// user through per-server consent, the client:////   1. holds an identity assertion from SSO with the IdP,//   2. exchanges it at the IdP for an Identity Assertion JWT Authorization//      Grant (ID-JAG) naming the MCP server's authorization server (§4.3), and//   3. redeems that ID-JAG at the Resource Authorization Server for an access//      token bound to the MCP server (§4.4).//// The IdP evaluates administrator policy at step 2, which is the whole point of// the profile (§7.2): the enterprise decides which users may reach which// servers with which scopes. That makes the error taxonomy below load-bearing// rather than cosmetic — see `EmaPolicyDenied`.//// This module owns the chain only. Discovery lives in `./oauth-discovery`, the// two token-endpoint round trips in `./oauth-helpers`, and persistence in the// executor's credential lifecycle.// --------------------------------------------------------------------------- import { Data, Effect, Option, Schema } from "effect"; import { IntegrationSlug, OAuthClientSlug, Owner } from "./ids";import {  DEFAULT_SUBJECT_TOKEN_TYPE,  SubjectTokenTypeSchema,  type SubjectTokenType,} from "./oauth-client";import {  ID_JAG_GRANT_PROFILE,  supportsIdJagGrantProfile,  type OAuthAuthorizationServerMetadata,} from "./oauth-discovery";import {  exchangeSubjectTokenForIdJag,  redeemIdJagAssertion,  type OAuth2Error,  type OAuth2TokenResponse,  type OAuthEndpointUrlPolicy,} from "./oauth-helpers"; // ---------------------------------------------------------------------------// Persisted connection state//// Everything the renewal path needs that is NOT already a column on the// connection or its `oauth_client` row. The `oauth_client` supplies the client's// registration at the Resource Authorization Server (id/secret/token URL/// resource); the connection supplies the granted scope and the identity// assertion (stored in the same credential-provider item a refresh token would// occupy — it plays exactly that role here). What remains is the pointer to the// IdP registration and the discovered `audience`, which cannot be derived from// either.// --------------------------------------------------------------------------- export const EnterpriseManagedConnectionStateSchema = Schema.Struct({  /** `oauth_client` slug of the client's registration at the enterprise IdP. */  idpClient: OAuthClientSlug,  idpClientOwner: Owner,  /** The Resource Authorization Server's issuer identifier, as discovered from   *  its RFC 8414 metadata when the connection was made. */  audience: Schema.String,  subjectTokenType: SubjectTokenTypeSchema,}).annotate({  identifier: "EnterpriseManagedConnectionState",  description:    "Enterprise-managed authorization wiring persisted on a connection: which IdP registration mints its ID-JAG, and the audience that ID-JAG must name.",});export type EnterpriseManagedConnectionState = typeof EnterpriseManagedConnectionStateSchema.Type; /** The key `EnterpriseManagedConnectionState` occupies inside a connection's *  `provider_state` JSON, alongside the other core-owned keys. */export const ENTERPRISE_MANAGED_PROVIDER_STATE_KEY = "enterpriseManaged"; const decodeEnterpriseManagedProviderState = Schema.decodeUnknownOption(  Schema.Struct({    [ENTERPRISE_MANAGED_PROVIDER_STATE_KEY]: EnterpriseManagedConnectionStateSchema,  }),); /** Read the enterprise-managed wiring off a connection's decoded *  `provider_state`, or null when the connection is not enterprise-managed. *  A malformed entry reads as absent — the refresh path then fails loudly with *  "not enterprise-managed" rather than half-running the chain on fragments. */export const enterpriseManagedStateFrom = (  providerState: unknown,): EnterpriseManagedConnectionState | null =>  Option.match(decodeEnterpriseManagedProviderState(providerState), {    onNone: () => null,    onSome: (decoded) => decoded[ENTERPRISE_MANAGED_PROVIDER_STATE_KEY],  }); // ---------------------------------------------------------------------------// Errors//// The distinctions here drive product behavior, so they are separate tags// rather than one error carrying a code:////   - `EmaGrantProfileUnsupported` is the ONLY failure that permits falling//     back to the ordinary interactive per-server OAuth flow. The server simply//     does not implement the profile.//   - `EmaPolicyDenied` and `EmaSubjectTokenRejected` MUST NOT fall back.//     Falling back would let a user route around the enterprise policy the IdP//     just enforced, which is precisely the control this profile exists to//     provide.// --------------------------------------------------------------------------- /** The Resource Authorization Server does not advertise the ID-JAG grant *  profile in its RFC 8414 metadata (draft §7.2). Enterprise-managed *  authorization is not available for this server; the caller MAY fall back to *  the ordinary interactive authorization-code flow. */export class EmaGrantProfileUnsupported extends Data.TaggedError("EmaGrantProfileUnsupported")<{  readonly issuer: string;  readonly advertised: readonly string[];}> {  override get message(): string {    return `The authorization server ${this.issuer} does not advertise ${ID_JAG_GRANT_PROFILE}${      this.advertised.length > 0 ? ` (advertised: ${this.advertised.join(", ")})` : ""    }.`;  }} /** The enterprise IdP refused to mint an ID-JAG for this client, user, resource *  or scope set. This is an administrator decision, not a credential problem: *  the user cannot fix it by signing in again, and the client MUST NOT offer *  the interactive per-server flow as an alternative route. Surface it as *  blocked-by-admin and stop. */export class EmaPolicyDenied extends Data.TaggedError("EmaPolicyDenied")<{  /** The IdP's RFC 6749 §5.2 error code (`unauthorized_client`, `access_denied`,   *  `invalid_target`, `invalid_scope`, `invalid_client`, …). */  readonly error: string;  readonly detail: string;}> {  override get message(): string {    return `Your organization's identity provider did not authorize this MCP server (${this.error}): ${this.detail}`;  }} /** The IdP rejected the identity assertion itself (RFC 6749 `invalid_grant`): *  expired, revoked, or issued for a different client. The user must sign in *  with the enterprise IdP again to obtain a fresh assertion. */export class EmaSubjectTokenRejected extends Data.TaggedError("EmaSubjectTokenRejected")<{  readonly detail: string;}> {  override get message(): string {    return `The enterprise identity assertion was rejected and a new single sign-on is required: ${this.detail}`;  }} /** The Resource Authorization Server refused the ID-JAG (draft §4.4.1): wrong *  `typ`, an `aud` naming a different authorization server, a `client_id` claim *  that does not match the authenticated client, a bad signature, or expiry. */export class EmaRedemptionRejected extends Data.TaggedError("EmaRedemptionRejected")<{  /** The Resource Authorization Server's RFC 6749 §5.2 code, when it returned one. */  readonly error: string | undefined;  readonly detail: string;}> {  override get message(): string {    return `The MCP server's authorization server rejected the identity assertion grant${      this.error === undefined ? "" : ` (${this.error})`    }: ${this.detail}`;  }} /** A token endpoint could not be reached, timed out, or answered with something *  that is not an OAuth response at all. Carries no authorization verdict, so *  it is retryable: the next attempt may well succeed. */export class EmaUpstreamUnavailable extends Data.TaggedError("EmaUpstreamUnavailable")<{  readonly step: "token-exchange" | "redemption";  readonly detail: string;}> {  override get message(): string {    return `The enterprise-managed authorization ${this.step} request failed: ${this.detail}`;  }} /** What running the two-step grant can fail with. Notably NOT *  `EmaGrantProfileUnsupported`: minting never inspects metadata, so it cannot *  reach that verdict, and callers of `mintEnterpriseManagedAccessToken` must *  not be made to write an arm for a case that cannot occur. */export type EnterpriseManagedMintError =  | EmaPolicyDenied  | EmaSubjectTokenRejected  | EmaRedemptionRejected  | EmaUpstreamUnavailable; /** Everything `runEnterpriseManagedAuthorization` can fail with: the mint *  failures plus the one discovery verdict only it can produce. */export type EnterpriseManagedAuthorizationError =  | EnterpriseManagedMintError  | EmaGrantProfileUnsupported; // ---------------------------------------------------------------------------// Configuration// --------------------------------------------------------------------------- /** The client's registration at the enterprise IdP — the relationship that *  authenticates the token-exchange request (draft §5: this is a DIFFERENT *  registration from the one at the Resource Authorization Server). */export interface EnterpriseIdentityProvider {  /** The IdP's token endpoint, where the RFC 8693 exchange is POSTed. */  readonly tokenUrl: string;  readonly clientId: string;  /** Empty or null for a public client the IdP does not authenticate. */  readonly clientSecret?: string | null;} /** The client's registration at the MCP server's Resource Authorization Server *  — the credentials that authenticate the ID-JAG redemption (draft §4.4). */export interface ResourceAuthorizationServerClient {  readonly tokenUrl: string;  /** The Resource Authorization Server's RFC 8414 issuer identifier. Sent as   *  the exchange's `audience` and validated by the server as the ID-JAG's   *  `aud` claim, which is what stops an ID-JAG minted for one server from   *  being replayed at another (draft §4.4.1). */  readonly issuer: string;  readonly clientId: string;  readonly clientSecret?: string | null;} export interface EnterpriseManagedAuthorizationInput {  readonly idp: EnterpriseIdentityProvider;  readonly resourceAuthorizationServer: ResourceAuthorizationServerClient;  /** The identity assertion obtained from single sign-on with the IdP. */  readonly subjectToken: string;  readonly subjectTokenType?: SubjectTokenType;  /** RFC 9728 resource identifier of the MCP server (EMA profile §4). */  readonly resource?: string | null;  readonly scopes?: readonly string[];  readonly timeoutMs?: number;  readonly endpointUrlPolicy?: OAuthEndpointUrlPolicy;  readonly fetch?: typeof globalThis.fetch;} /** An access token minted through the ID-JAG chain, plus the scope the Resource *  Authorization Server actually granted. There is no refresh token by design *  (draft §4.4.3): renewal re-runs the chain. */export interface EnterpriseManagedGrant {  readonly token: OAuth2TokenResponse;  /** Granted scope as echoed by the Resource Authorization Server, falling back   *  to what the IdP recorded in the ID-JAG. Null when neither said. */  readonly scope: string | null;} // ---------------------------------------------------------------------------// The chain// --------------------------------------------------------------------------- const exchangeFailure = (cause: OAuth2Error): EnterpriseManagedMintError => {  // oxlint-disable-next-line executor/no-unknown-error-message -- boundary: OAuth2Error declares `message` as a field; this is a typed failure, not an unknown throwable  const detail = cause.message;  // RFC 6749 §5.2: `invalid_grant` is the code for a grant that is invalid,  // expired or revoked — here, the identity assertion the client presented. Any  // OTHER definitive code is the IdP declining to authorize this client for  // this target, which is an administrator decision.  if (cause.error === "invalid_grant") {    return new EmaSubjectTokenRejected({ detail });  }  if (cause.error !== undefined) {    return new EmaPolicyDenied({ error: cause.error, detail });  }  return new EmaUpstreamUnavailable({ step: "token-exchange", detail });}; const redemptionFailure = (cause: OAuth2Error): EnterpriseManagedMintError => {  // oxlint-disable-next-line executor/no-unknown-error-message -- boundary: see `exchangeFailure` above  const detail = cause.message;  return cause.error === undefined    ? new EmaUpstreamUnavailable({ step: "redemption", detail })    : new EmaRedemptionRejected({ error: cause.error, detail });}; /** Run the two-step grant: exchange the identity assertion for an ID-JAG at the *  IdP, then redeem the ID-JAG at the Resource Authorization Server. * *  The ID-JAG is deliberately NOT retained. Draft §4.4.3 lets a client re-submit *  a still-valid ID-JAG when only the access token expired, but that saves one *  round trip at the cost of persisting a second bearer-equivalent credential *  whose expiry the client would then have to track. Re-running the exchange is *  the simpler correct behavior and is what §4.4.3 prescribes once the ID-JAG *  itself has expired. */export const mintEnterpriseManagedAccessToken = (  input: EnterpriseManagedAuthorizationInput,): Effect.Effect<EnterpriseManagedGrant, EnterpriseManagedMintError> =>  Effect.gen(function* () {    const grant = yield* exchangeSubjectTokenForIdJag({      tokenUrl: input.idp.tokenUrl,      clientId: input.idp.clientId,      clientSecret: input.idp.clientSecret,      subjectToken: input.subjectToken,      subjectTokenType: input.subjectTokenType ?? DEFAULT_SUBJECT_TOKEN_TYPE,      audience: input.resourceAuthorizationServer.issuer,      resource: input.resource,      scopes: input.scopes,      timeoutMs: input.timeoutMs,      endpointUrlPolicy: input.endpointUrlPolicy,      fetch: input.fetch,    }).pipe(Effect.mapError(exchangeFailure));     // Re-request only what the IdP granted. Policy MAY narrow the set (§4.3.3),    // and asking the Resource Authorization Server for more than the ID-JAG    // carries would be asking it to exceed the enterprise's own decision.    const grantedScopes =      grant.scope === undefined ? input.scopes : grant.scope.split(/\s+/).filter(Boolean);     const token = yield* redeemIdJagAssertion({      tokenUrl: input.resourceAuthorizationServer.tokenUrl,      issuerUrl: input.resourceAuthorizationServer.issuer,      clientId: input.resourceAuthorizationServer.clientId,      clientSecret: input.resourceAuthorizationServer.clientSecret,      assertion: grant.assertion,      resource: input.resource,      scopes: grantedScopes,      timeoutMs: input.timeoutMs,      endpointUrlPolicy: input.endpointUrlPolicy,      fetch: input.fetch,    }).pipe(Effect.mapError(redemptionFailure));     return {      token,      scope: token.scope ?? grant.scope ?? null,    } satisfies EnterpriseManagedGrant;  }).pipe(    Effect.withSpan("executor.oauth.enterprise_managed", {      attributes: { "executor.oauth.has_resource": input.resource != null },    }),  ); /** Detect the profile on the target's discovered metadata, then run the chain. *  The connect path uses this; the credential-refresh path calls *  `mintEnterpriseManagedAccessToken` directly, because the profile was already *  confirmed when the connection was made and re-discovering it on every token *  renewal would add a round trip that can only ever confirm what is stored. */export const runEnterpriseManagedAuthorization = (  input: Omit<EnterpriseManagedAuthorizationInput, "resourceAuthorizationServer"> & {    readonly authorizationServerMetadata: OAuthAuthorizationServerMetadata;    readonly resourceAuthorizationServer: Omit<      ResourceAuthorizationServerClient,      "tokenUrl" | "issuer"    >;  },): Effect.Effect<EnterpriseManagedGrant, EnterpriseManagedAuthorizationError> =>  Effect.suspend<EnterpriseManagedGrant, EnterpriseManagedAuthorizationError, never>(() => {    const metadata = input.authorizationServerMetadata;    if (!supportsIdJagGrantProfile(metadata)) {      return Effect.fail(        new EmaGrantProfileUnsupported({          issuer: metadata.issuer,          advertised: metadata.authorization_grant_profiles_supported ?? [],        }),      );    }    return mintEnterpriseManagedAccessToken({      ...input,      resourceAuthorizationServer: {        ...input.resourceAuthorizationServer,        tokenUrl: metadata.token_endpoint,        issuer: metadata.issuer,      },    });  }); // ---------------------------------------------------------------------------// Rollout gate//// Enterprise-managed authorization is shipped behind a host-owned rollout gate.// The SDK declares the PORT and stays vendor-free: no feature-flag service, no// analytics client, no network dependency of its own. A host that has one// injects an implementation through `OAuthServiceDeps`; a host that has none// (desktop, CLI, local, self-hosted) injects nothing and the profile behaves// exactly as it did before the gate existed.//// Two properties are load-bearing and are pinned by tests// (`oauth-ema-rollout.test.ts`):////   1. The gate is consulted EXACTLY ONCE per connect, BEFORE discovery, and//      NEVER after the IdP has spoken. A policy denial that could be re-routed//      through a flag check would turn the flag into an escape hatch around the//      very enterprise control this profile exists to enforce.////   2. The gate is a CONNECT-time decision only. It is recorded on the//      connection (`ENTERPRISE_MANAGED_PROVIDER_STATE_KEY`) and the//      credential-refresh path follows the stored state, never the gate. So//      turning the flag off stops NEW enterprise-managed connects and leaves//      every existing managed connection renewing untouched — and no//      third-party network dependency ever enters credential resolution.// --------------------------------------------------------------------------- /** Who is connecting, as far as a rollout gate needs to know. Carries identity *  and catalog identifiers only — never the identity assertion, the client *  secret, or any other credential material. */export interface EnterpriseManagedRolloutContext {  /** The acting user, as the host identifies them. Null when the executor is   *  bound to an org-level caller with no individual subject. */  readonly userId: string | null;  /** The organization the executor is bound to, when the host names one. */  readonly organizationId: string | null;  /** The integration being connected. A spec-derived catalog slug, safe to   *  report; the `oauth_client` slug is deliberately NOT here, because a   *  user-registered client's slug is user-entered text. */  readonly integration: IntegrationSlug;} /** Why the gate withheld the enterprise-managed path. Kept structural so a host *  can tell "the operator has not enabled this yet" apart from "we could not *  find out", which are the same user-visible behavior but different *  operational events. */export type EnterpriseManagedRolloutWithheldReason =  /** The gate answered, and the answer was no. */  | "disabled"  /** The gate could not reach a decision (timeout, transport failure,   *  unusable answer, missing configuration) and failed closed. */  | "evaluation-unavailable"; /** The gate's verdict on one connect. */export type EnterpriseManagedRolloutDecision =  | { readonly kind: "enabled" }  | { readonly kind: "withheld"; readonly reason: EnterpriseManagedRolloutWithheldReason }; /** What happened on a connect against a client whose grant is `id_jag`, for a *  host that records rollout analytics. * *  Every variant carries the context and the gate's decision and NOTHING else *  that could be sensitive: there is no field here that can hold a token, an *  identity assertion, a client secret, or a scope value. */export type EnterpriseManagedRolloutEvent =  /** A connect reached the enterprise-managed branch. Fires for BOTH arms of   *  the rollout — read `decision` for which — so the funnel below it has a   *  denominator. */  | {      readonly kind: "attempted";      readonly context: EnterpriseManagedRolloutContext;      readonly decision: EnterpriseManagedRolloutDecision;    }  /** The ID-JAG chain completed and a connection was minted. */  | {      readonly kind: "connected";      readonly context: EnterpriseManagedRolloutContext;      readonly decision: EnterpriseManagedRolloutDecision;    }  /** The enterprise IdP declined to authorize this user for this server. */  | {      readonly kind: "blocked-by-admin";      readonly context: EnterpriseManagedRolloutContext;      readonly decision: EnterpriseManagedRolloutDecision;      /** The IdP's RFC 6749 §5.2 error code, when it returned one. */      readonly oauthErrorCode: string | undefined;    }; /** The host-owned rollout seam for enterprise-managed authorization. * *  `decide` is the gate: it MUST NOT fail, because a rollout mechanism that can *  fail a connect is worse than no rollout mechanism. An implementation that *  cannot reach a verdict returns *  `{ kind: "withheld", reason: "evaluation-unavailable" }` — failing closed — *  rather than failing the effect. * *  `record` is a best-effort observer. The OAuth service runs it with its *  failures and defects discarded, so it can neither fail a connect nor change *  its outcome no matter what the implementation does. */export interface EnterpriseManagedRollout {  readonly decide: (    context: EnterpriseManagedRolloutContext,  ) => Effect.Effect<EnterpriseManagedRolloutDecision>;  readonly record: (event: EnterpriseManagedRolloutEvent) => Effect.Effect<void>;} /** The decision that applies when no host injected a gate: enterprise-managed *  authorization is attempted, which is the behavior every host had before the *  rollout seam existed. */export const ENTERPRISE_MANAGED_ROLLOUT_ENABLED: EnterpriseManagedRolloutDecision = {  kind: "enabled",};