Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(control-api): add generic AS discovery (issuer-first) and prefill
Diego Zacarias9560494b99fb
diff --git a/control-api/package-lock.json b/control-api/package-lock.jsonindex 07501440f..a5035d477 100644--- a/control-api/package-lock.json+++ b/control-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-api",- "version": "0.1.606",+ "version": "0.1.607","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-api",- "version": "0.1.606",+ "version": "0.1.607","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.jsonindex 0f2f7f103..59d3d2ffd 100644--- a/control-api/package.json+++ b/control-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-api",- "version": "0.1.606",+ "version": "0.1.607","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/discovery.ts b/control-api/src/oauth/discovery.tsindex b79850821..33d85cbca 100644--- a/control-api/src/oauth/discovery.ts+++ b/control-api/src/oauth/discovery.ts@@ -643,3 +643,247 @@ export async function discoverRemoteOAuth(},}}++// ─── Generic self-hosted AS discovery (S3-B4 / E-19.5, D-A6) ─────────────────+//+// A separate entry point from `discoverRemoteOAuth` (which stays byte-identical,+// C1/C1.5 golden): the generic operator typically types an AS ISSUER, not a+// protected MCP resource. This resolves RFC 8414 / OIDC metadata ISSUER-FIRST+// (DA-2), falling back to RFC 9728 PRM only when the issuer path yields no AS. It+// reuses the same private primitives (`guardedFetchJson`, `asMetadataUrls`,+// `isIssuerConsistentWithBase`, `resolvePrm`, `deriveQuirks`) and has NO S256 gate:+// a generic client may legally run with `usePkce:false`, so PKCE support is REPORTED+// as a suggestion, never enforced.++/** Result of generic AS discovery. `prm`/`resource` present only via the PRM fallback. */+export interface AsDiscoveryResult {+ as: AuthorizationServerMetadata+ prm?: ProtectedResourceMetadata+ issuer: string+ endpoints: { authorization: string; token: string }+ /** RFC 8707 resource — only when reached through a protected-resource-metadata document. */+ resource?: string+}++export type AsDiscoveryOutcome =+ | { ok: true; result: AsDiscoveryResult }+ | { ok: false; error: DiscoveryError }++/**+ * Fetch + validate RFC 8414 / OIDC AS metadata from an authorization-server base URL,+ * trying both well-known forms. Mirrors the AS-metadata loop inside+ * {@link discoverRemoteOAuth} MINUS the S256 gate; kept separate so that golden path+ * stays byte-identical. Issuer is checked against the base (RFC 8414 §3.3).+ */+async function resolveAsMetadataFromBase(+ asBaseUrl: URL,+ deps: DiscoveryDeps+): Promise<{ ok: true; as: AuthorizationServerMetadata } | { ok: false; error: DiscoveryError }> {+ let lastError: DiscoveryError = {+ kind: 'fetch_failed',+ url: asBaseUrl.toString(),+ detail: 'no AS-metadata candidate resolved',+ }+ for (const url of asMetadataUrls(asBaseUrl)) {+ const fetched = await guardedFetchJson(url, 'asMetadataUrl', deps)+ if (!fetched.ok) {+ lastError = fetched.error+ continue+ }+ if (!isRecord(fetched.json)) {+ lastError = { kind: 'invalid_metadata', url, detail: 'AS metadata is not an object' }+ continue+ }+ const candidate = fetched.json as AuthorizationServerMetadata+ if (+ typeof candidate.issuer !== 'string' ||+ typeof candidate.authorization_endpoint !== 'string' ||+ typeof candidate.token_endpoint !== 'string'+ ) {+ lastError = {+ kind: 'invalid_metadata',+ url,+ detail: 'AS metadata missing issuer/authorization_endpoint/token_endpoint',+ }+ continue+ }+ if (!isIssuerConsistentWithBase(candidate.issuer, asBaseUrl)) {+ lastError = {+ kind: 'issuer_mismatch',+ detail: `AS issuer "${candidate.issuer}" does not match authorization server "${asBaseUrl.toString()}"`,+ }+ continue+ }+ return { ok: true, as: candidate }+ }+ return { ok: false, error: lastError }+}++/**+ * Discover an authorization server's metadata for the generic carril. `url` is the+ * operator-typed AS issuer (or, in the fallback, a protected MCP resource). Every+ * fetched/pinned URL passes the kernel BEFORE the fetch (spec 19 §4), including the+ * typed URL and every discovered endpoint. Fail-closed: an AS that advertises an+ * internal/blocked endpoint is rejected (`kernel_rejected`), never pre-filled.+ */+export async function discoverAuthorizationServerMetadata(+ url: string,+ deps: DiscoveryDeps+): Promise<AsDiscoveryOutcome> {+ const log = (deps.logger ?? rootLogger).child({ module: 'oauth-discovery' })++ let base: URL+ try {+ base = new URL(url)+ } catch {+ return {+ ok: false,+ error: { kind: 'invalid_metadata', url, detail: 'url is not a valid absolute URL' },+ }+ }++ let as: AuthorizationServerMetadata+ let prm: ProtectedResourceMetadata | undefined+ let resource: string | undefined++ // Issuer-first (DA-2): the typed URL is most likely an AS issuer.+ const issuerFirst = await resolveAsMetadataFromBase(base, deps)+ if (issuerFirst.ok) {+ as = issuerFirst.as+ } else {+ // PRM fallback (RFC 9728 → 8414): treat the URL as a protected resource, resolve+ // its PRM and follow authorization_servers[0]. Reuses the remote-lane PRM resolver+ // (kernel-guards + pins every candidate). On total failure we surface the+ // issuer-first error — that is the path the operator's input targeted.+ const prmResult = await resolvePrm(url, deps)+ if (!prmResult.ok) {+ log.warn(+ { issuerFirst: issuerFirst.error.kind, prm: prmResult.error.kind },+ 'generic AS discovery failed (issuer-first and PRM fallback)'+ )+ return { ok: false, error: issuerFirst.error }+ }+ prm = prmResult.prm+ const asBase = prm.authorization_servers?.[0]+ if (typeof asBase !== 'string' || asBase.length === 0) {+ return {+ ok: false,+ error: { kind: 'no_authorization_server', detail: 'PRM has no authorization_servers[0]' },+ }+ }+ let asBaseUrl: URL+ try {+ asBaseUrl = new URL(asBase)+ } catch {+ return {+ ok: false,+ error: {+ kind: 'invalid_metadata',+ url: asBase,+ detail: 'authorization_servers[0] is not a valid URL',+ },+ }+ }+ const asViaPrm = await resolveAsMetadataFromBase(asBaseUrl, deps)+ if (!asViaPrm.ok) {+ log.warn({ discovery: asViaPrm.error.kind }, 'generic AS discovery failed (PRM → AS)')+ return { ok: false, error: asViaPrm.error }+ }+ as = asViaPrm.as+ resource = prm.resource+ }++ // Kernel-guard every discovered endpoint BEFORE it is pinned/suggested (spec §4):+ // an AS that announces an internal endpoint must not be pre-filled.+ const endpointChecks: Array<{ field: string; url: string }> = [+ { field: 'spec.oauth.authorizationEndpoint', url: as.authorization_endpoint },+ { field: 'spec.oauth.tokenEndpoint', url: as.token_endpoint },+ ]+ for (const check of endpointChecks) {+ const errors = await validateOAuthEndpointUrl(check.url, check.field, {+ resolveDns: deps.resolveDns,+ })+ if (errors.length > 0) {+ return { ok: false, error: { kind: 'kernel_rejected', field: check.field, errors } }+ }+ }++ return {+ ok: true,+ result: {+ as,+ prm,+ issuer: as.issuer,+ endpoints: { authorization: as.authorization_endpoint, token: as.token_endpoint },+ resource,+ },+ }+}++/** Suggestion wire the generic install wizard pre-fills from (E-19.5, §5.2). */+export interface GenericDiscoveryPrefill {+ issuer: string+ endpoints: { authorization: string; token: string }+ /** Only when discovery went through a protected-resource-metadata document. */+ resource?: string+ scopesSupported: string[]+ /** Raw AS advertisements, shown in the wizard "Detected" panel. */+ capabilities: {+ codeChallengeMethods: string[]+ tokenEndpointAuthMethods: string[]+ grantTypes: string[]+ }+ /** Deterministic, documented derivations (§5.2). */+ suggested: {+ usePkce: boolean+ tokenAuthMethod: 'body' | 'basic'+ supportsRefresh: boolean+ }+}++function stringArray(value: unknown): string[] {+ return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []+}++function definedStringArray(value: unknown): string[] | undefined {+ return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : undefined+}++/**+ * Project an {@link AsDiscoveryResult} onto the wizard prefill wire (§5.2). Pure and+ * deterministic. Absent metadata never invents a value: `usePkce` is false without an+ * advertised S256 (invariant 7), `tokenAuthMethod` is `basic` only when the AS lists+ * `client_secret_basic` and NOT `client_secret_post`, `supportsRefresh` reuses the+ * fail-closed `deriveQuirks` rule (D4). Fields with no standard metadata+ * (tokenRequestFormat, scopeSeparator, sendScope, includeResponseType,+ * extraAuthorizeParams, refreshEndpoint) are never suggested here.+ */+export function buildGenericDiscoveryPrefill(result: AsDiscoveryResult): GenericDiscoveryPrefill {+ const as = result.as+ const codeChallengeMethods = stringArray(as.code_challenge_methods_supported)+ const tokenEndpointAuthMethods = stringArray(as.token_endpoint_auth_methods_supported)+ const grantTypes = stringArray(as.grant_types_supported)+ const scopesSupported =+ definedStringArray(result.prm?.scopes_supported) ??+ definedStringArray(as.scopes_supported) ??+ []+ const tokenAuthMethod: 'body' | 'basic' =+ tokenEndpointAuthMethods.includes('client_secret_basic') &&+ !tokenEndpointAuthMethods.includes('client_secret_post')+ ? 'basic'+ : 'body'+ return {+ issuer: result.issuer,+ endpoints: result.endpoints,+ ...(result.resource ? { resource: result.resource } : {}),+ scopesSupported,+ capabilities: { codeChallengeMethods, tokenEndpointAuthMethods, grantTypes },+ suggested: {+ usePkce: codeChallengeMethods.includes('S256'),+ tokenAuthMethod,+ // Reuse the fail-closed refresh rule; prm is optional for it (bearerInBody unused).+ supportsRefresh: deriveQuirks(as, result.prm ?? ({} as ProtectedResourceMetadata))+ .supportsRefresh,+ },+ }+}diff --git a/control-api/test/oauth.discovery.generic.test.ts b/control-api/test/oauth.discovery.generic.test.tsnew file mode 100644index 000000000..5841ad3a4--- /dev/null+++ b/control-api/test/oauth.discovery.generic.test.ts@@ -0,0 +1,148 @@+import { describe, expect, it, vi } from 'vitest'+import type { PinnedRawResponse, PinnedTransport } from '../src/http/pinnedFetch.js'+import {+ type DiscoveryDeps,+ buildGenericDiscoveryPrefill,+ discoverAuthorizationServerMetadata,+} from '../src/oauth/discovery.js'+import {+ CANVA_AS_JSON,+ LINEAR_AS_JSON,+ NOTION_AS_JSON,+ PILOTS,+ SENTRY_AS_JSON,+ makeDiscoveryTransport,+} from './fixtures/remoteOAuthDiscovery.js'++/**+ * S3-B4 / E-19.5 — generic AS discovery (issuer-first → PRM, DA-2). Fixtures are the+ * real 2026-09-20 probe bytes (T1): the four pilots expose RFC 8414 / OIDC AS+ * metadata, which is exactly the issuer-first shape. No S256 gate (inv.7); every URL+ * kernel-guarded before the fetch (inv.6).+ */+const PUBLIC_IP = ['93.184.216.34']+const publicDns = () => vi.fn(async () => PUBLIC_IP)+function deps(transport: PinnedTransport, resolveDns = publicDns()): DiscoveryDeps {+ return { transport, resolveDns }+}++/** Transport that serves ONE AS well-known URL, 404 elsewhere (issuer-first shape). */+function asOnlyTransport(asWellKnownUrl: string, json: string): PinnedTransport {+ return async ({ url }: { url: string }): Promise<PinnedRawResponse> => {+ if (url === asWellKnownUrl) {+ return { status: 200, headers: { 'content-type': 'application/json' }, bodyText: json }+ }+ return { status: 404, headers: {}, bodyText: 'not found' }+ }+}++const AS_BY_PILOT: Record<'notion' | 'linear' | 'sentry' | 'canva', string> = {+ notion: NOTION_AS_JSON,+ linear: LINEAR_AS_JSON,+ sentry: SENTRY_AS_JSON,+ canva: CANVA_AS_JSON,+}++describe('discoverAuthorizationServerMetadata — issuer-first (T1 real fixtures)', () => {+ for (const key of ['notion', 'linear', 'sentry', 'canva'] as const) {+ it(`${key}: resolves AS metadata directly from the issuer`, async () => {+ const as = JSON.parse(AS_BY_PILOT[key])+ // Issuer origin (path-less AS) → well-known oauth-authorization-server.+ const issuer: string = as.issuer+ const asWellKnown = `${issuer}/.well-known/oauth-authorization-server`+ const outcome = await discoverAuthorizationServerMetadata(+ issuer,+ deps(asOnlyTransport(asWellKnown, AS_BY_PILOT[key]))+ )+ expect(outcome.ok).toBe(true)+ if (!outcome.ok) return+ expect(outcome.result.issuer).toBe(as.issuer)+ expect(outcome.result.endpoints.authorization).toBe(as.authorization_endpoint)+ expect(outcome.result.endpoints.token).toBe(as.token_endpoint)+ // Issuer-first carries no PRM / resource.+ expect(outcome.result.prm).toBeUndefined()+ expect(outcome.result.resource).toBeUndefined()+ })+ }++ it('projects the prefill wire deterministically (notion)', async () => {+ const asWellKnown = 'https://mcp.notion.com/.well-known/oauth-authorization-server'+ const outcome = await discoverAuthorizationServerMetadata(+ 'https://mcp.notion.com',+ deps(asOnlyTransport(asWellKnown, NOTION_AS_JSON))+ )+ expect(outcome.ok).toBe(true)+ if (!outcome.ok) return+ const prefill = buildGenericDiscoveryPrefill(outcome.result)+ // Notion advertises S256 (+plain), refresh_token, and both basic+post → body.+ expect(prefill.suggested.usePkce).toBe(true)+ expect(prefill.suggested.supportsRefresh).toBe(true)+ expect(prefill.suggested.tokenAuthMethod).toBe('body')+ expect(prefill.capabilities.codeChallengeMethods).toContain('S256')+ expect(prefill.scopesSupported).toEqual(['default'])+ expect(prefill.resource).toBeUndefined()+ })++ // PRM fallback (RFC 9728 → 8414): a protected-resource URL, no AS at the issuer.+ it('falls back to PRM when the URL is a protected resource, carrying resource', async () => {+ const outcome = await discoverAuthorizationServerMetadata(+ PILOTS.notion.mcpUrl,+ deps(makeDiscoveryTransport(PILOTS.notion))+ )+ expect(outcome.ok).toBe(true)+ if (!outcome.ok) return+ expect(outcome.result.prm).toBeDefined()+ expect(outcome.result.resource).toBe('https://mcp.notion.com')+ const prefill = buildGenericDiscoveryPrefill(outcome.result)+ expect(prefill.resource).toBe('https://mcp.notion.com')+ })+})++describe('discoverAuthorizationServerMetadata — no S256 gate (inv.7)', () => {+ it('accepts an AS without code_challenge_methods_supported; usePkce suggested false', async () => {+ // Derived from the real Notion AS by documented subtraction (T1): drop the PKCE+ // advertisement. Discovery must NOT fail closed (unlike the remote lane).+ const as = JSON.parse(NOTION_AS_JSON) as Record<string, unknown>+ delete as.code_challenge_methods_supported+ const json = JSON.stringify(as)+ const asWellKnown = 'https://mcp.notion.com/.well-known/oauth-authorization-server'+ const outcome = await discoverAuthorizationServerMetadata(+ 'https://mcp.notion.com',+ deps(asOnlyTransport(asWellKnown, json))+ )+ expect(outcome.ok).toBe(true)+ if (!outcome.ok) return+ const prefill = buildGenericDiscoveryPrefill(outcome.result)+ expect(prefill.suggested.usePkce).toBe(false)+ expect(prefill.capabilities.codeChallengeMethods).toEqual([])+ })+})++describe('discoverAuthorizationServerMetadata — kernel §4 (inv.6)', () => {+ it('never opens a socket to a kernel-rejected (internal) URL', async () => {+ const transport = vi.fn(async () => ({ status: 200, headers: {}, bodyText: '{}' }))+ const outcome = await discoverAuthorizationServerMetadata(+ 'https://as.svc.cluster.local',+ deps(transport as unknown as PinnedTransport)+ )+ expect(outcome.ok).toBe(false)+ // Internal hostname is rejected pre-DNS, pre-connect: zero transport calls.+ expect(transport).toHaveBeenCalledTimes(0)+ })++ it('rejects an AS that advertises an internal authorization endpoint', async () => {+ // Real Notion AS with the authorize endpoint mutated to an internal host — the+ // metadata fetch succeeds, but the discovered endpoint fails the kernel.+ const as = JSON.parse(NOTION_AS_JSON) as Record<string, unknown>+ as.authorization_endpoint = 'https://authorize.svc.cluster.local/authorize'+ const json = JSON.stringify(as)+ const asWellKnown = 'https://mcp.notion.com/.well-known/oauth-authorization-server'+ const outcome = await discoverAuthorizationServerMetadata(+ 'https://mcp.notion.com',+ deps(asOnlyTransport(asWellKnown, json))+ )+ expect(outcome.ok).toBe(false)+ if (outcome.ok) return+ expect(outcome.error.kind).toBe('kernel_rejected')+ })+})