Skip to content

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

TypeScript

feat(control-api): add closed authorization-server profiles (entra-v2)

Diego Zacarias807c4fa185bc
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index bbd5e34b6..85dad5b60 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.788",
+ "version": "0.1.789",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.788",
+ "version": "0.1.789",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index e6a3f89d3..09d267298 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.788",
+ "version": "0.1.789",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/oauth/asProfiles.ts b/control-api/src/oauth/asProfiles.ts
new file mode 100644
index 000000000..23e2a4e63
--- /dev/null
+++ b/control-api/src/oauth/asProfiles.ts
@@ -0,0 +1,212 @@
+/**
+ * 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 the refresh request. */
+ refreshWithScope: 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 tokens must never reach an MCP host, whatever the operator confirms. */
+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'],
+])
+
+/** 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, refreshWithScope: false })
+const WIRE_ENTRA_V2: RemoteWire = Object.freeze({ sendResource: false, refreshWithScope: 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]
+ return { kind: ENTRA_BLOCKED_RESOURCE_APPS.has(guid) ? 'blocked-guid' : 'guid', 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. */
+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 cannot be tied to the MCP host: accepted only when
+ * the operator confirms each one. 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.get(guid as string) !== host
+ })
+ 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
+}
diff --git a/control-api/test/oauth.asProfiles.test.ts b/control-api/test/oauth.asProfiles.test.ts
new file mode 100644
index 000000000..0edf173ef
--- /dev/null
+++ b/control-api/test/oauth.asProfiles.test.ts
@@ -0,0 +1,493 @@
+import { describe, expect, it } from 'vitest'
+import fc from 'fast-check'
+import {
+ AS_PROFILE_IDS,
+ ENTRA_BLOCKED_RESOURCE_APPS,
+ ENTRA_KNOWN_RESOURCE_APPS,
+ ENTRA_TENANT_AUTHORITY_TEMPLATE,
+ ENTRA_TENANT_ISSUER_PATTERN,
+ SCOPE_TOKEN_RE,
+ asProfileById,
+ detectAsProfile,
+ isAsProfileId,
+ isEntraMultiTenantAuthority,
+ isEntraTenantAuthority,
+ profileHasResourceScope,
+ profileScopeViolation,
+ profileUnverifiedScopes,
+ remoteWireForProfile,
+ withProfileScopes,
+} from '../src/oauth/asProfiles.js'
+import { ENTRA_AGENT365_MAIL_PILOT, ENTRA_WORKIQ_PILOT } from './fixtures/remoteOAuthDiscovery.js'
+
+const TENANT = '72f988bf-86f1-41af-91ab-2d7cd011db47'
+const TENANT_ISSUER = `https://login.microsoftonline.com/${TENANT}/v2.0`
+const WORKIQ_URL = ENTRA_WORKIQ_PILOT.mcpUrl
+const AGENT365_URL = ENTRA_AGENT365_MAIL_PILOT.mcpUrl
+const WORKIQ_GUID_SCOPE = 'fdcc1f02-fc51-4226-8753-f668596af7f7/WorkIQAgent.Ask'
+const AGENT365_GUID_SCOPE = '05879165-0320-489e-b644-f72b33f3edf0/McpServers.Mail.All'
+const UNKNOWN_GUID_SCOPE = '11111111-2222-3333-4444-555555555555/Tools.Read'
+
+// Literal copies of the closed tables: a typo or a dropped entry in the module must
+// turn this red, so these are written out, never derived from the Map under test.
+const BLOCKED_LITERAL: Array<[string, string]> = [
+ ['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'],
+]
+const KNOWN_LITERAL: Array<[string, string]> = [
+ ['fdcc1f02-fc51-4226-8753-f668596af7f7', 'workiq.svc.cloud.microsoft'],
+ ['05879165-0320-489e-b644-f72b33f3edf0', 'agent365.svc.cloud.microsoft'],
+]
+
+describe('closed tables', () => {
+ it('ENTRA_BLOCKED_RESOURCE_APPS is exactly the 11 high-impact first-party APIs', () => {
+ expect([...ENTRA_BLOCKED_RESOURCE_APPS.entries()]).toEqual(BLOCKED_LITERAL)
+ })
+
+ it('ENTRA_KNOWN_RESOURCE_APPS ties exactly Work IQ and Agent 365 Tools to their hosts', () => {
+ expect([...ENTRA_KNOWN_RESOURCE_APPS.entries()]).toEqual(KNOWN_LITERAL)
+ })
+
+ it('constants', () => {
+ expect(AS_PROFILE_IDS).toEqual(['entra-v2'])
+ expect(ENTRA_TENANT_AUTHORITY_TEMPLATE).toBe(
+ 'https://login.microsoftonline.com/{tenantId}/v2.0'
+ )
+ expect(ENTRA_TENANT_ISSUER_PATTERN).toBe(
+ '^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$'
+ )
+ })
+})
+
+describe('detectAsProfile / isEntraTenantAuthority', () => {
+ it('recognises the tenant issuer the real Entra tenant metadata declares', () => {
+ const issuer = JSON.parse(ENTRA_WORKIQ_PILOT.as.json).issuer as string
+ expect(issuer).toBe(TENANT_ISSUER)
+ const profile = detectAsProfile(issuer)
+ expect(profile).toEqual({
+ id: 'entra-v2',
+ pkceS256: true,
+ supportsRefresh: true,
+ requiredScopes: ['offline_access'],
+ })
+ expect(Object.isFrozen(profile)).toBe(true)
+ expect(Object.isFrozen(profile?.requiredScopes)).toBe(true)
+ expect(profile).toBe(asProfileById('entra-v2'))
+ expect(isEntraTenantAuthority(issuer)).toBe(true)
+ })
+
+ const organizationsIssuer = JSON.parse(ENTRA_WORKIQ_PILOT.asExtra?.[0].json ?? '{}')
+ .issuer as string
+ for (const issuer of [
+ `https://login.microsoftonline.com/${TENANT.toUpperCase()}/v2.0`,
+ 'https://login.microsoftonline.com/common/v2.0',
+ 'https://login.microsoftonline.com/organizations/v2.0',
+ organizationsIssuer,
+ 'https://login.microsoftonline.com/{tenantid}/v2.0',
+ `${TENANT_ISSUER}/`,
+ `https://login.microsoftonline.us/${TENANT}/v2.0`,
+ `https://login.partner.microsoftonline.cn/${TENANT}/v2.0`,
+ `https://login.microsoftonline.de/${TENANT}/v2.0`,
+ `http://login.microsoftonline.com/${TENANT}/v2.0`,
+ `${TENANT_ISSUER}?`,
+ `${TENANT_ISSUER}?x=1`,
+ `${TENANT_ISSUER}#`,
+ `${TENANT_ISSUER}#f`,
+ `https://login.microsoftonline.com:443/${TENANT}/v2.0`,
+ `https://[email protected]/${TENANT}/v2.0`,
+ `https://login.microsoftonline.com/${TENANT}/v2.0\n`,
+ `https://loginXmicrosoftonline.com/${TENANT}/v2.0`,
+ `https://login.microsoftonline.com/${TENANT}/v2x0`,
+ `https://sts.windows.net/${TENANT}/`,
+ 'https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0',
+ '',
+ ]) {
+ it(`null for ${JSON.stringify(issuer)}`, () => {
+ expect(detectAsProfile(issuer)).toBeNull()
+ expect(isEntraTenantAuthority(issuer)).toBe(false)
+ })
+ }
+
+ const guidArb = fc.uuid().map(u => u.toLowerCase())
+ const issuerArb = fc.oneof(
+ fc.string(),
+ fc.stringMatching(new RegExp(ENTRA_TENANT_ISSUER_PATTERN)),
+ fc
+ .tuple(
+ fc.constantFrom('https://', 'http://', 'https://u@'),
+ fc.constantFrom(
+ 'login.microsoftonline.com',
+ 'login.microsoftonline.us',
+ 'LOGIN.microsoftonline.com'
+ ),
+ fc.oneof(
+ guidArb,
+ guidArb.map(g => g.toUpperCase()),
+ fc.constantFrom('common', 'organizations')
+ ),
+ fc.constantFrom('/v2.0', '/v2.0/', '/v2.0?', '/v2.0#', '/v1.0', '')
+ )
+ .map(([scheme, host, tenant, tail]) => `${scheme}${host}/${tenant}${tail}`)
+ )
+
+ it('property: detectAsProfile(s) !== null iff s matches ENTRA_TENANT_ISSUER_PATTERN', () => {
+ const re = new RegExp(ENTRA_TENANT_ISSUER_PATTERN)
+ fc.assert(
+ fc.property(issuerArb, s => {
+ expect(detectAsProfile(s) !== null).toBe(re.test(s))
+ })
+ )
+ })
+
+ it('property: isEntraTenantAuthority agrees with detectAsProfile', () => {
+ fc.assert(
+ fc.property(issuerArb, s => {
+ expect(isEntraTenantAuthority(s)).toBe(detectAsProfile(s) !== null)
+ })
+ )
+ })
+})
+
+describe('isAsProfileId / asProfileById / remoteWireForProfile', () => {
+ it('isAsProfileId accepts only entra-v2', () => {
+ expect(isAsProfileId('entra-v2')).toBe(true)
+ for (const v of ['Entra-v2', 'entra-v1', 'entra', '', undefined, null, 1, {}, ['entra-v2']]) {
+ expect(isAsProfileId(v)).toBe(false)
+ }
+ })
+
+ it('remoteWireForProfile', () => {
+ expect(remoteWireForProfile(undefined)).toEqual({ sendResource: true, refreshWithScope: false })
+ expect(remoteWireForProfile('entra-v2')).toEqual({
+ sendResource: false,
+ refreshWithScope: true,
+ })
+ })
+})
+
+describe('withProfileScopes', () => {
+ it('without a profile returns a copy of the scopes as-is', () => {
+ const scopes = ['a', 'b', 'a']
+ const out = withProfileScopes(scopes, undefined)
+ expect(out).toEqual(['a', 'b', 'a'])
+ expect(out).not.toBe(scopes)
+ })
+
+ it('entra-v2 appends offline_access when missing, dedupes and keeps order', () => {
+ expect(withProfileScopes([WORKIQ_GUID_SCOPE], 'entra-v2')).toEqual([
+ WORKIQ_GUID_SCOPE,
+ 'offline_access',
+ ])
+ expect(withProfileScopes(['offline_access', 'x', 'x'], 'entra-v2')).toEqual([
+ 'offline_access',
+ 'x',
+ ])
+ expect(withProfileScopes([], 'entra-v2')).toEqual(['offline_access'])
+ })
+
+ it('entra-v2 does not duplicate the offline_access the real Agent 365 PRM already carries', () => {
+ const prmScopes = JSON.parse(ENTRA_AGENT365_MAIL_PILOT.prm.json).scopes_supported as string[]
+ expect(withProfileScopes(prmScopes, 'entra-v2')).toEqual(prmScopes)
+ })
+
+ it('property: idempotent, duplicate-free and always contains offline_access with the profile', () => {
+ const scopeArb = fc.array(fc.constantFrom('a', 'b', 'offline_access', 'openid', 'c/x'), {
+ maxLength: 8,
+ })
+ fc.assert(
+ fc.property(scopeArb, scopes => {
+ const once = withProfileScopes(scopes, 'entra-v2')
+ expect(withProfileScopes(once, 'entra-v2')).toEqual(once)
+ expect(new Set(once).size).toBe(once.length)
+ expect(once).toContain('offline_access')
+ expect(once.filter(s => s !== 'offline_access')).toEqual(
+ [...new Set(scopes)].filter(s => s !== 'offline_access')
+ )
+ })
+ )
+ })
+})
+
+describe('profileScopeViolation', () => {
+ it('null without a profile, whatever the scopes', () => {
+ expect(profileScopeViolation(undefined, WORKIQ_URL, ['Mail.Read', 'bad scope'])).toBeNull()
+ })
+
+ const accepted: Array<[string, string]> = [
+ [WORKIQ_URL, WORKIQ_GUID_SCOPE],
+ [WORKIQ_URL, 'api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask'],
+ [WORKIQ_URL, 'https://workiq.svc.cloud.microsoft/WorkIQAgent.Ask'],
+ [
+ AGENT365_URL,
+ `https://agent365.svc.cloud.microsoft/agents/tenants/${TENANT}/servers/mcp_MailTools/.default`,
+ ],
+ [WORKIQ_URL, 'offline_access'],
+ [WORKIQ_URL, 'openid'],
+ [WORKIQ_URL, 'profile'],
+ [WORKIQ_URL, 'email'],
+ [AGENT365_URL, AGENT365_GUID_SCOPE],
+ [AGENT365_URL, `api://${AGENT365_GUID_SCOPE}`],
+ // Not rejected: whether it can be tied to the host is profileUnverifiedScopes' call.
+ [WORKIQ_URL, UNKNOWN_GUID_SCOPE],
+ ]
+ for (const [base, scope] of accepted) {
+ it(`accepts ${scope}`, () => {
+ expect(profileScopeViolation('entra-v2', base, [scope])).toBeNull()
+ })
+ }
+
+ it('accepts every scope of the real Work IQ and Agent 365 PRMs', () => {
+ for (const pilot of [ENTRA_WORKIQ_PILOT, ENTRA_AGENT365_MAIL_PILOT]) {
+ const scopes = JSON.parse(pilot.prm.json).scopes_supported as string[]
+ expect(profileScopeViolation('entra-v2', pilot.mcpUrl, scopes)).toBeNull()
+ }
+ })
+
+ const blockedGuids = [
+ '00000003-0000-0000-c000-000000000000',
+ '00000003-0000-0ff1-ce00-000000000000',
+ '00000002-0000-0ff1-ce00-000000000000',
+ '797f4846-ba00-4fd7-ba43-dac1f8f63013',
+ '00000002-0000-0000-c000-000000000000',
+ 'cfa8b339-82a2-471a-a3c9-0fc0be7a4093',
+ 'e406a681-f3d4-42a8-90b6-c2b029497af1',
+ 'c5393580-f805-4401-95e8-94b7a6ef2fc2',
+ '0000000a-0000-0000-c000-000000000000',
+ 'fc780465-2017-40d4-a0c5-307022471b92',
+ '00000004-0000-0ff1-ce00-000000000000',
+ ]
+ const rejected = [
+ 'https://graph.microsoft.com/Mail.Read',
+ 'Mail.Read',
+ ...blockedGuids.flatMap(guid => [`${guid}/x`, `api://${guid}/x`]),
+ 'api://evil.example/x',
+ 'https://[mal',
+ 'api://[email protected]/Mail.Read',
+ 'https://[email protected]/Mail.Read',
+ 'https://workiq.svc.cloud.microsoft:443/x',
+ 'https://WORKIQ.svc.cloud.microsoft/x',
+ `api://${TENANT}/myapp/Read`,
+ 'https://workiq.svc.cloud.microsoft\\x',
+ 'https://workiq.svc.cloud.microsoft/a b',
+ 'api://workiq.svc.cloud.microsoft/a"b',
+ 'https://workiq.svc.cloud.microsoft.evil.example/x',
+ 'https://workiq.svc.cloud.microsoft',
+ 'FDCC1F02-FC51-4226-8753-F668596AF7F7/WorkIQAgent.Ask',
+ '',
+ ]
+ for (const scope of rejected) {
+ it(`rejects ${JSON.stringify(scope)}`, () => {
+ expect(profileScopeViolation('entra-v2', WORKIQ_URL, [scope])).toBe(scope)
+ })
+ }
+
+ it('the 11 blocked GUIDs are rejected in both forms (written as literals)', () => {
+ expect(blockedGuids).toHaveLength(11)
+ for (const guid of blockedGuids) {
+ expect(profileScopeViolation('entra-v2', WORKIQ_URL, [`${guid}/x`])).toBe(`${guid}/x`)
+ expect(profileScopeViolation('entra-v2', WORKIQ_URL, [`api://${guid}/x`])).toBe(
+ `api://${guid}/x`
+ )
+ }
+ })
+
+ it('returns the first rejected scope, in order', () => {
+ expect(
+ profileScopeViolation('entra-v2', WORKIQ_URL, [
+ WORKIQ_GUID_SCOPE,
+ 'offline_access',
+ 'Mail.Read',
+ 'https://graph.microsoft.com/x',
+ ])
+ ).toBe('Mail.Read')
+ })
+})
+
+describe('profileHasResourceScope', () => {
+ it('false with the profile when only OIDC scopes (or none) are requested', () => {
+ for (const scopes of [
+ ['offline_access'],
+ ['openid', 'profile', 'email', 'offline_access'],
+ [],
+ ]) {
+ expect(profileHasResourceScope('entra-v2', WORKIQ_URL, scopes)).toBe(false)
+ }
+ })
+
+ it('true with any scope accepted by the GUID or host-URL rule', () => {
+ for (const scope of [
+ WORKIQ_GUID_SCOPE,
+ UNKNOWN_GUID_SCOPE,
+ 'api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask',
+ 'https://workiq.svc.cloud.microsoft/x',
+ ]) {
+ expect(profileHasResourceScope('entra-v2', WORKIQ_URL, ['offline_access', scope])).toBe(true)
+ }
+ })
+
+ it('false when the only non-OIDC scopes are rejected ones', () => {
+ for (const scope of [
+ 'Mail.Read',
+ 'https://graph.microsoft.com/x',
+ '00000003-0000-0000-c000-000000000000/x',
+ 'https://workiq.svc.cloud.microsoft/a b',
+ ]) {
+ expect(profileHasResourceScope('entra-v2', WORKIQ_URL, ['openid', scope])).toBe(false)
+ }
+ })
+
+ it('true without a profile', () => {
+ expect(profileHasResourceScope(undefined, WORKIQ_URL, [])).toBe(true)
+ expect(profileHasResourceScope(undefined, WORKIQ_URL, ['offline_access'])).toBe(true)
+ })
+})
+
+describe('profileUnverifiedScopes', () => {
+ it('[] for the known GUIDs on their own host (both forms), the URL form and OIDC', () => {
+ expect(
+ profileUnverifiedScopes('entra-v2', WORKIQ_URL, [
+ WORKIQ_GUID_SCOPE,
+ `api://${WORKIQ_GUID_SCOPE}`,
+ 'api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask',
+ 'openid',
+ 'profile',
+ 'email',
+ 'offline_access',
+ ])
+ ).toEqual([])
+ expect(
+ profileUnverifiedScopes('entra-v2', AGENT365_URL, [
+ AGENT365_GUID_SCOPE,
+ `api://${AGENT365_GUID_SCOPE}`,
+ `https://agent365.svc.cloud.microsoft/agents/tenants/${TENANT}/servers/mcp_MailTools/.default`,
+ ])
+ ).toEqual([])
+ })
+
+ it('an unknown GUID is unverified (order kept, no duplicates)', () => {
+ expect(
+ profileUnverifiedScopes('entra-v2', WORKIQ_URL, [
+ UNKNOWN_GUID_SCOPE,
+ WORKIQ_GUID_SCOPE,
+ `api://${UNKNOWN_GUID_SCOPE}`,
+ UNKNOWN_GUID_SCOPE,
+ ])
+ ).toEqual([UNKNOWN_GUID_SCOPE, `api://${UNKNOWN_GUID_SCOPE}`])
+ })
+
+ it('a known GUID on another host is unverified', () => {
+ expect(profileUnverifiedScopes('entra-v2', WORKIQ_URL, [AGENT365_GUID_SCOPE])).toEqual([
+ AGENT365_GUID_SCOPE,
+ ])
+ expect(profileUnverifiedScopes('entra-v2', AGENT365_URL, [WORKIQ_GUID_SCOPE])).toEqual([
+ WORKIQ_GUID_SCOPE,
+ ])
+ })
+
+ it('a blocked GUID is never unverified (it is rejected instead)', () => {
+ expect(
+ profileUnverifiedScopes('entra-v2', WORKIQ_URL, ['00000003-0000-0000-c000-000000000000/x'])
+ ).toEqual([])
+ })
+
+ it('[] without a profile', () => {
+ expect(profileUnverifiedScopes(undefined, WORKIQ_URL, [UNKNOWN_GUID_SCOPE])).toEqual([])
+ })
+})
+
+describe('audience classification properties', () => {
+ const knownOrBlockedGuid = fc.constantFrom(
+ ...BLOCKED_LITERAL.map(([g]) => g),
+ ...KNOWN_LITERAL.map(([g]) => g)
+ )
+ const guidArb = fc.oneof(
+ knownOrBlockedGuid,
+ fc.uuid().map(u => u.toLowerCase()),
+ fc.uuid()
+ )
+ const hostArb = fc.constantFrom(
+ 'workiq.svc.cloud.microsoft',
+ 'agent365.svc.cloud.microsoft',
+ 'graph.microsoft.com',
+ 'evil.example'
+ )
+ const scopeArb = fc.oneof(
+ fc.string(),
+ fc.constantFrom('openid', 'profile', 'email', 'offline_access', 'Mail.Read'),
+ fc
+ .tuple(fc.constantFrom('', 'api://'), guidArb, fc.string({ minLength: 1 }))
+ .map(([p, g, name]) => `${p}${g}/${name}`),
+ fc
+ .tuple(
+ fc.constantFrom('https://', 'api://'),
+ hostArb,
+ fc.constantFrom('/', ':443/', '@x/'),
+ fc.string()
+ )
+ .map(([p, h, sep, rest]) => `${p}${h}${sep}${rest}`)
+ )
+ const baseArb = hostArb.map(h => `https://${h}/mcp`)
+
+ it('no scope is both a violation and unverified; a blocked GUID is never unverified', () => {
+ fc.assert(
+ fc.property(baseArb, scopeArb, (base, scope) => {
+ const violation = profileScopeViolation('entra-v2', base, [scope])
+ const unverified = profileUnverifiedScopes('entra-v2', base, [scope])
+ expect(violation !== null && unverified.includes(scope)).toBe(false)
+ const guid = /^(?:api:\/\/)?([0-9a-f-]{36})\//.exec(scope)?.[1]
+ if (guid !== undefined && BLOCKED_LITERAL.some(([g]) => g === guid)) {
+ expect(unverified).toEqual([])
+ }
+ })
+ )
+ })
+
+ it('every scope the profile accepts is an RFC 6749 scope-token', () => {
+ fc.assert(
+ fc.property(baseArb, scopeArb, (base, scope) => {
+ if (profileScopeViolation('entra-v2', base, [scope]) === null) {
+ expect(SCOPE_TOKEN_RE.test(scope)).toBe(true)
+ }
+ })
+ )
+ })
+})
+
+describe('isEntraMultiTenantAuthority', () => {
+ const yes = [
+ 'https://login.microsoftonline.com/organizations/v2.0',
+ 'https://login.microsoftonline.com/common/v2.0',
+ 'https://login.microsoftonline.com/organizations/v2.0/',
+ 'https://login.microsoftonline.com/common/v2.0//',
+ JSON.parse(ENTRA_WORKIQ_PILOT.prm.json).authorization_servers[0] as string,
+ JSON.parse(ENTRA_AGENT365_MAIL_PILOT.prm.json).authorization_servers[0] as string,
+ ]
+ const no = [
+ TENANT_ISSUER,
+ 'http://login.microsoftonline.com/organizations/v2.0',
+ 'https://login.microsoftonline.com:8443/organizations/v2.0',
+ 'https://login.microsoftonline.com/organizations/v2.0?x=1',
+ 'https://login.microsoftonline.com/organizations/v2.0#f',
+ 'https://u:[email protected]/organizations/v2.0',
+ 'https://login.microsoftonline.us/organizations/v2.0',
+ 'https://login.microsoftonline.com/consumers/v2.0',
+ 'https://login.microsoftonline.com/organizations',
+ 'https://login.microsoftonline.com/organizations/v2.0/extra',
+ 'https://evil.example/organizations/v2.0',
+ ]
+ for (const url of yes) {
+ it(`true for ${url}`, () => expect(isEntraMultiTenantAuthority(new URL(url))).toBe(true))
+ }
+ for (const url of no) {
+ it(`false for ${url}`, () => expect(isEntraMultiTenantAuthority(new URL(url))).toBe(false))
+ }
+})