Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
10.9 KB
Raw Blame
/**
 * Authorization-server profiles: closed, code-defined behaviour for authorization
 * servers whose published metadata omits capabilities they document elsewhere. A
 * profile is recognised ONLY from an issuer that already passed the strict RFC 8414
 * §3.3 comparison, so it never widens which issuers are trusted.
 *
 * `entra-v2` — Microsoft Entra ID v2, tenant authority. Why each rule exists:
 * - Entra's OIDC metadata omits `code_challenge_methods_supported` and
 *   `grant_types_supported`, yet its authorization code flow reference
 *   (learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow) states that
 *   it supports both `plain` and `S256`, that the `refresh_token` is "only provided if
 *   `offline_access` scope was requested", and that the refresh request accepts a
 *   `scope` "equivalent to or a subset of" the scopes of the authorize request. Hence
 *   PKCE S256 and refresh are assumed, and `offline_access` is always requested.
 * - Entra v2 resolves the token audience from `scope` and rejects an RFC 8707
 *   `resource` that disagrees with it (AADSTS9010010), so `resource` is never sent and
 *   the scopes alone decide which API the token is for.
 * - A scope without a resource prefix (`Mail.Read`) is read by Entra as a Microsoft
 *   Graph scope. Every resource scope must therefore name the MCP server's own host,
 *   or be the GUID form of an API this module can tie to that host.
 * - Entra allows dynamic consent to permissions the app registration does not declare
 *   (learn.microsoft.com/entra/identity-platform/consent-types-developer), so the app
 *   registration does not cap which API a GUID-form scope can reach. That is why
 *   high-impact first-party APIs are rejected outright and any other GUID the host
 *   cannot be tied to needs the operator's explicit confirmation.
 * - Requesting only OIDC scopes returns a Microsoft Graph token for UserInfo
 *   (learn.microsoft.com/entra/identity-platform/scopes-oidc), so at least one resource
 *   scope is required.
 */

export type AsProfileId = 'entra-v2'
export const AS_PROFILE_IDS: readonly AsProfileId[] = Object.freeze(['entra-v2'] as const)

export interface AsProfile {
  id: AsProfileId
  /** Supports PKCE S256 although its metadata omits code_challenge_methods_supported. */
  pkceS256: true
  /** Issues refresh tokens when `offline_access` is requested. */
  supportsRefresh: true
  /** Scopes always added to the requested set (order kept, no duplicates). */
  requiredScopes: readonly string[]
}

export interface RemoteWire {
  /** Send RFC 8707 `resource` on authorize, token and refresh. */
  sendResource: boolean
  /** Send the requested scopes as `scope` on every token-endpoint request (code exchange and refresh). */
  scopeOnTokenRequests: boolean
}

/** The CEL-compatible issuer pattern; the CRD rule and `detectAsProfile` share this exact text. */
export const ENTRA_TENANT_ISSUER_PATTERN =
  '^https://login[.]microsoftonline[.]com/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/v2[.]0$'

export const ENTRA_TENANT_AUTHORITY_TEMPLATE = 'https://login.microsoftonline.com/{tenantId}/v2.0'

/** RFC 6749 §3.3 scope-token; remoteMcp.ts imports it from here. */
export const SCOPE_TOKEN_RE = /^[\x21\x23-\x5B\x5D-\x7E]+$/

/**
 * First-party APIs whose GUID-form scopes are always rejected, whatever the operator confirms:
 * a GUID names no host, so a confirmed one would let Entra mint a token for these high-impact
 * APIs and hand it to whatever MCP host the CR points at.
 *
 * Only the GUID form is blocked. A first-party MCP server whose audience lives on its own host
 * (for example Dataverse at <org>.crm.dynamics.com/api/mcp) is connected with that host's
 * URL-form scope, which the host rule already accepts.
 *
 * Left out on purpose, because their URL-form audience lives on a host other than their MCP
 * server, so the GUID form (confirmed by the operator) is the only way to connect them:
 * - Azure DevOps (499b84ac-1321-427f-aa17-267ca6975798), MCP server at mcp.dev.azure.com;
 * - Power BI Service (00000009-0000-0000-c000-000000000000), MCP server at
 *   api.fabric.microsoft.com while its URL audience is analysis.windows.net.
 */
export const ENTRA_BLOCKED_RESOURCE_APPS: ReadonlyMap<string, string> = new Map([
  ['00000003-0000-0000-c000-000000000000', 'Microsoft Graph'],
  ['00000003-0000-0ff1-ce00-000000000000', 'SharePoint Online'],
  ['00000002-0000-0ff1-ce00-000000000000', 'Exchange Online'],
  ['797f4846-ba00-4fd7-ba43-dac1f8f63013', 'Azure Service Management'],
  ['00000002-0000-0000-c000-000000000000', 'Azure AD Graph'],
  ['cfa8b339-82a2-471a-a3c9-0fc0be7a4093', 'Azure Key Vault'],
  ['e406a681-f3d4-42a8-90b6-c2b029497af1', 'Azure Storage'],
  ['c5393580-f805-4401-95e8-94b7a6ef2fc2', 'Office 365 Management APIs'],
  ['0000000a-0000-0000-c000-000000000000', 'Microsoft Intune'],
  ['fc780465-2017-40d4-a0c5-307022471b92', 'WindowsDefenderATP'],
  ['00000004-0000-0ff1-ce00-000000000000', 'Skype for Business Online'],
  ['00000007-0000-0000-c000-000000000000', 'Dynamics CRM'],
  ['022907d3-0f1b-48f7-badc-1ba6abab6d66', 'Azure SQL Database'],
  ['ca7f3f0b-7d91-482c-8e09-c5d840d0eac5', 'Log Analytics API'],
  ['48ac35b8-9aa8-4d74-927d-1f4a14a0b239', 'Skype and Teams Tenant Admin API'],
  ['cc15fd57-2c6c-4117-a88c-83b1d56b4bbe', 'Microsoft Teams Services'],
])

/** First-party MCP APIs tied to the only host allowed to receive their tokens. */
export const ENTRA_KNOWN_RESOURCE_APPS: ReadonlyMap<string, string> = new Map([
  ['fdcc1f02-fc51-4226-8753-f668596af7f7', 'workiq.svc.cloud.microsoft'],
  ['05879165-0320-489e-b644-f72b33f3edf0', 'agent365.svc.cloud.microsoft'],
])

const ENTRA_V2: AsProfile = Object.freeze({
  id: 'entra-v2',
  pkceS256: true,
  supportsRefresh: true,
  requiredScopes: Object.freeze(['offline_access']),
})

const WIRE_DEFAULT: RemoteWire = Object.freeze({ sendResource: true, scopeOnTokenRequests: false })
const WIRE_ENTRA_V2: RemoteWire = Object.freeze({ sendResource: false, scopeOnTokenRequests: true })

const ENTRA_TENANT_ISSUER_RE = new RegExp(ENTRA_TENANT_ISSUER_PATTERN)
const ENTRA_LOGIN_HOST = 'login.microsoftonline.com'
const ENTRA_MULTI_TENANT_PATHS: ReadonlySet<string> = new Set([
  '/common/v2.0',
  '/organizations/v2.0',
])
const OIDC_SCOPES: ReadonlySet<string> = new Set(['openid', 'profile', 'email', 'offline_access'])
const GUID_SCOPE_RE =
  /^(api:\/\/)?([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/[^/]+$/

export function isAsProfileId(value: unknown): value is AsProfileId {
  return value === 'entra-v2'
}

export function detectAsProfile(issuer: string): AsProfile | null {
  return ENTRA_TENANT_ISSUER_RE.test(issuer) ? ENTRA_V2 : null
}

/** The profile constant for an id (the same object detectAsProfile returns). */
export function asProfileById(id: AsProfileId): AsProfile {
  switch (id) {
    case 'entra-v2':
      return ENTRA_V2
  }
}

export function remoteWireForProfile(id: AsProfileId | undefined): RemoteWire {
  return id === 'entra-v2' ? WIRE_ENTRA_V2 : WIRE_DEFAULT
}

/** `scopes` plus the profile's required scopes, first occurrence wins; `scopes` as-is without a profile. */
export function withProfileScopes(
  scopes: readonly string[],
  id: AsProfileId | undefined
): string[] {
  if (id === undefined) return [...scopes]
  return [...new Set([...scopes, ...asProfileById(id).requiredScopes])]
}

type ScopeClass = 'invalid' | 'oidc' | 'blocked-guid' | 'guid' | 'host-url' | 'foreign'

/** The `entra-v2` audience rule, applied to one scope; `host` is the MCP server's hostname. */
function classifyEntraScope(scope: string, host: string): { kind: ScopeClass; guid?: string } {
  if (!SCOPE_TOKEN_RE.test(scope)) return { kind: 'invalid' }
  if (OIDC_SCOPES.has(scope)) return { kind: 'oidc' }
  const guidForm = GUID_SCOPE_RE.exec(scope)
  if (guidForm) {
    const guid = guidForm[2]
    if (ENTRA_BLOCKED_RESOURCE_APPS.has(guid)) return { kind: 'blocked-guid', guid }
    // A known API has one legitimate host, so on any other host its token is a leak, not
    // something the operator could confirm; this also catches a base URL edited after the
    // install, which the runtime re-check classifies with the same rule.
    const knownHost = ENTRA_KNOWN_RESOURCE_APPS.get(guid)
    return { kind: knownHost === undefined || knownHost === host ? 'guid' : 'foreign', guid }
  }
  // A literal prefix, never `new URL`: WHATWG parsing accepts userinfo and a port, so
  // `api://<graph-guid>@<host>/x` would otherwise report the MCP host.
  if (scope.startsWith(`https://${host}/`) || scope.startsWith(`api://${host}/`)) {
    return { kind: 'host-url' }
  }
  return { kind: 'foreign' }
}

function isRejected(kind: ScopeClass): boolean {
  return kind === 'invalid' || kind === 'blocked-guid' || kind === 'foreign'
}

/**
 * The first scope that breaks the profile's audience rule, or null. `null` too without a
 * profile. An empty scope is itself a violation and comes back as `''`, so callers must
 * test `!== null`, never truthiness.
 */
export function profileScopeViolation(
  id: AsProfileId | undefined,
  mcpBaseUrl: string,
  scopes: readonly string[]
): string | null {
  if (id === undefined) return null
  const host = new URL(mcpBaseUrl).hostname
  return scopes.find(scope => isRejected(classifyEntraScope(scope, host).kind)) ?? null
}

/** False when, with a profile, no scope names a resource (only OIDC scopes → a Microsoft Graph token). True without a profile. */
export function profileHasResourceScope(
  id: AsProfileId | undefined,
  mcpBaseUrl: string,
  scopes: readonly string[]
): boolean {
  if (id === undefined) return true
  const host = new URL(mcpBaseUrl).hostname
  return scopes.some(scope => {
    const { kind } = classifyEntraScope(scope, host)
    return kind === 'guid' || kind === 'host-url'
  })
}

/**
 * Scopes in GUID form whose API the platform does not know, so it cannot tie them to the
 * MCP host: accepted only when the operator confirms each one. A known API on another
 * host is a violation instead. Empty without a profile. Order kept, no duplicates.
 */
export function profileUnverifiedScopes(
  id: AsProfileId | undefined,
  mcpBaseUrl: string,
  scopes: readonly string[]
): string[] {
  if (id === undefined) return []
  const host = new URL(mcpBaseUrl).hostname
  const unverified = scopes.filter(scope => {
    const { kind, guid } = classifyEntraScope(scope, host)
    return kind === 'guid' && !ENTRA_KNOWN_RESOURCE_APPS.has(guid as string)
  })
  return [...new Set(unverified)]
}

export function isEntraMultiTenantAuthority(url: URL): boolean {
  return (
    url.protocol === 'https:' &&
    url.hostname === ENTRA_LOGIN_HOST &&
    url.port === '' &&
    url.search === '' &&
    url.hash === '' &&
    url.username === '' &&
    url.password === '' &&
    ENTRA_MULTI_TENANT_PATHS.has(url.pathname.replace(/\/+$/, ''))
  )
}

/** True for exactly `https://login.microsoftonline.com/<lower-case guid>/v2.0` (no trailing slash, query, fragment, port or userinfo). */
export function isEntraTenantAuthority(value: string): boolean {
  return detectAsProfile(value) !== null
}