wizards 0.1.9

package/apps/runtime/dist/engenty/connections-external/build-connector.js

@@ -0,0 +1,193 @@
+import { decryptToken, defineConnector, } from "../shims/connections-sdk.js";
+import { z } from "zod";
+import { headersFromRequired } from "./import-service.js";
+import { executeHttpAction } from "./invoke/http-invoker.js";
+import { mcpCallTool } from "./invoke/mcp-client.js";
+import { connectionsRedirectUri, registerDynamicClient } from "./oauth-dcr.js";
+/**
+ * Materialize a stored import record into a live `ConnectorDefinition`. From
+ * here on the framework owns everything — per-action operations, policy
+ * defaults by group, approvals, accounts, audit — identical to a hand-written
+ * provider.
+ */
+/**
+ * MCP request headers: the connector's required headers first, then the
+ * credential — auth must win a name collision, never the other way round.
+ */
+export function mcpHeaders(record, accessToken) {
+    const headers = headersFromRequired(record.required_headers);
+    const auth = record.auth_config;
+    if (auth.kind === "oauth2") {
+        return { ...headers, authorization: `Bearer ${accessToken}` };
+    }
+    if (auth.kind === "api_key" && auth.placement.in === "header") {
+        let credentials = {};
+        try {
+            credentials = JSON.parse(accessToken);
+        }
+        catch {
+            return headers;
+        }
+        const value = auth.placement.value_template.replace(/\{\{\s*([a-z0-9_]+)\s*\}\}/giu, (_m, key) => credentials[key] ?? "");
+        return { ...headers, [auth.placement.name]: value };
+    }
+    return headers;
+}
+function inputSchemaToZod(action) {
+    try {
+        const schema = z.fromJSONSchema(action.input_json_schema);
+        return schema instanceof z.ZodObject ? schema : z.object({}).loose();
+    }
+    catch {
+        return null;
+    }
+}
+function buildAction(record, action, live) {
+    const inputSchema = inputSchemaToZod(action);
+    if (!inputSchema) {
+        return null;
+    }
+    const group = action.classification === "read"
+        ? "read"
+        : action.classification === "destructive"
+            ? "destructive"
+            : "write";
+    return {
+        description: action.description.slice(0, 1024),
+        group,
+        handler: (input, ctx) => {
+            // Read the record through the live resolver: refresh updates base_url/
+            // auth without re-binding the already-registered operation closures.
+            const current = live();
+            const args = (input ?? {});
+            if (action.invoke.kind === "mcp") {
+                return mcpCallTool({
+                    args,
+                    endpoint: current.source_url,
+                    headers: mcpHeaders(current, ctx.accessToken),
+                    toolName: action.invoke.tool_name,
+                    transport: current.mcp_transport,
+                });
+            }
+            return executeHttpAction({
+                accessToken: ctx.accessToken,
+                fetchImpl: ctx.fetchImpl,
+                input: args,
+                invoke: action.invoke,
+                record: current,
+            });
+        },
+        id: action.id,
+        inputSchema,
+        summary: action.summary.slice(0, 256),
+    };
+}
+function buildAuth(record, live, persistOAuthClient) {
+    const stored = record.auth_config;
+    if (stored.kind === "oauth2") {
+        const dcr = stored.dcr === true && Boolean(stored.registration_endpoint?.trim());
+        return {
+            kind: "oauth2",
+            oauth2: {
+                authUrl: stored.auth_url,
+                baseScopes: stored.scopes,
+                dynamicClientRegistration: dcr,
+                registerClient: dcr && persistOAuthClient
+                    ? async () => {
+                        const current = live();
+                        // Public DCR clients store only client_id_enc (empty secret).
+                        if (current.client_id_enc) {
+                            return;
+                        }
+                        const endpoint = current.auth_config.kind === "oauth2"
+                            ? current.auth_config.registration_endpoint
+                            : stored.registration_endpoint;
+                        if (!endpoint) {
+                            throw new Error(`imported connector ${current.id} has no OAuth registration endpoint`);
+                        }
+                        const registered = await registerDynamicClient({
+                            clientName: current.name,
+                            redirectUri: connectionsRedirectUri(),
+                            registrationEndpoint: endpoint,
+                            scopes: current.auth_config.kind === "oauth2"
+                                ? current.auth_config.scopes
+                                : stored.scopes,
+                        });
+                        await persistOAuthClient(registered);
+                    }
+                    : undefined,
+                resolveClientCredentials: () => {
+                    const current = live();
+                    if (!current.client_id_enc) {
+                        return Promise.reject(new Error(`imported connector ${current.id} has no OAuth client credentials — set them in the import console`));
+                    }
+                    return Promise.resolve({
+                        clientId: decryptToken(current.client_id_enc),
+                        clientSecret: current.client_secret_enc
+                            ? decryptToken(current.client_secret_enc)
+                            : "",
+                    });
+                },
+                scopeSeparator: stored.scope_separator ?? " ",
+                tokenUrl: stored.token_url,
+            },
+        };
+    }
+    if (stored.kind === "api_key") {
+        return {
+            apiKey: {
+                fields: stored.fields.map((field) => ({
+                    key: field.key,
+                    label: field.label,
+                    required: field.required ?? true,
+                    secret: field.secret ?? true,
+                })),
+                // No live probe on connect: imported specs give no reliable cheap
+                // "whoami" endpoint; a bad key surfaces on first action instead.
+                verify: (credentials) => {
+                    for (const field of stored.fields) {
+                        if ((field.required ?? true) && !credentials[field.key]) {
+                            return Promise.reject(new Error(`missing credential field "${field.key}"`));
+                        }
+                    }
+                    return Promise.resolve({ label: record.domain });
+                },
+            },
+            kind: "api_key",
+        };
+    }
+    // "none": model as api_key with zero fields so connect works without input.
+    return {
+        apiKey: {
+            fields: [],
+            verify: () => Promise.resolve({ label: record.domain }),
+        },
+        kind: "api_key",
+    };
+}
+export function buildImportedConnector(record, resolveLive, persistOAuthClient) {
+    const live = () => resolveLive?.() ?? record;
+    const actions = [];
+    const skippedActions = [];
+    for (const normalized of record.actions) {
+        const action = buildAction(record, normalized, live);
+        if (action) {
+            actions.push(action);
+        }
+        else {
+            skippedActions.push(normalized.id);
+        }
+    }
+    const connector = defineConnector({
+        actions,
+        auth: buildAuth(record, live, persistOAuthClient),
+        description: `${record.name} — imported from ${record.domain} (${record.source_kind})`,
+        icon: "plug",
+        id: record.id,
+        moduleId: "connections-external",
+        name: record.name,
+        tenantId: record.tenant_id,
+        toolPrefix: record.tool_prefix,
+    });
+    return { connector, skippedActions };
+}

package/apps/runtime/dist/engenty/connections-external/errors.js

@@ -0,0 +1,11 @@
+/**
+ * Import-time rejection. Routes answer 422 for this and 502 for everything
+ * else, so anything an admin can fix by choosing a different source, filling a
+ * field, or picking another surface must be raised as this error.
+ */
+export class ImportValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImportValidationError";
+    }
+}

package/apps/runtime/dist/engenty/connections-external/import-service.js

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import { encryptToken, getConnectorDefinition } from "../shims/connections-sdk.js";
+import { ImportValidationError } from "./errors.js";
+import { mapAuth } from "./importer/map-auth.js";
+import { normalizeMcpServer } from "./importer/normalize-mcp.js";
+import { MAX_SPEC_BYTES, normalizeOpenApiSpec, } from "./importer/normalize-openapi.js";
+import { isUnauthorizedMcpError } from "./invoke/mcp-client.js";
+import { createGuardedFetch, fetchTextBounded } from "./net/guarded-fetch.js";
+import { resolveMcpTransport, } from "./registry-client.js";
+/**
+ * Import/refresh pipeline shared by the admin routes: fetch source → apply the
+ * registry's spec overrides → normalize → map auth → assemble the stored
+ * record. Pure of DB and registry-transport concerns — the routes/plugin own
+ * persistence, registry lookups and (re-)registration.
+ *
+ * Every registry fact this pipeline reads is either applied or refuses the
+ * import. A surface that needs a URL variable, an environment-sourced header,
+ * or auth we cannot express never becomes a half-working connector.
+ */
+const SPEC_FETCH_TIMEOUT_MS = 30_000;
+/** Operation/tool ids must satisfy core's strict snake_case tool-id contract. */
+const TOOL_PREFIX_RE = /^[a-z][a-z0-9_]{1,30}$/u;
+export function validateConnectorNaming(params) {
+    if (!/^[a-z][a-z0-9-]{1,59}$/u.test(params.id)) {
+        throw new ImportValidationError(`connector id "${params.id}" must be kebab-case (a-z, 0-9, -)`);
+    }
+    if (!TOOL_PREFIX_RE.test(params.toolPrefix)) {
+        throw new ImportValidationError(`tool prefix "${params.toolPrefix}" must be snake_case, start with a letter, and stay short`);
+    }
+    const existing = getConnectorDefinition(params.id, params.tenantId);
+    if (existing && existing.moduleId !== "connections-external") {
+        throw new ImportValidationError(`connector id "${params.id}" collides with built-in connector "${existing.name}"`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Registry surface → import decisions
+// ---------------------------------------------------------------------------
+/** Connector id suggested by a registry surface slug ("stripe-mcp-server"). */
+export function connectorIdFromSlug(slug) {
+    return slug
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^[-0-9]+|-+$/gu, "")
+        .slice(0, 60);
+}
+/** Tool prefix suggested by a registry surface slug ("stripe_mcp_server"). */
+export function toolPrefixFromSlug(slug) {
+    return slug
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "_")
+        .replace(/^[_0-9]+|_+$/gu, "")
+        .slice(0, 30);
+}
+/**
+ * Static headers the API requires on every request. The registry also sources
+ * headers from the environment of the machine that talks to the API; those
+ * have no value we could store, so they block the import rather than being
+ * dropped on the floor.
+ */
+export function resolveRequiredHeaders(surface) {
+    const headers = [];
+    for (const header of surface.required_headers) {
+        const kind = header.source?.kind ?? "unknown";
+        if (kind !== "static") {
+            throw new ImportValidationError(`the registry requires header "${header.name}" from a ${kind} source — only static header values can be stored on an imported connector`);
+        }
+        const value = header.source?.value;
+        if (!value) {
+            throw new ImportValidationError(`the registry requires header "${header.name}" but publishes no value for it`);
+        }
+        headers.push({
+            description: header.description ?? null,
+            name: header.name,
+            value,
+        });
+    }
+    return headers;
+}
+/** Registry variables have no value at import time — reject, never guess. */
+export function assertNoRegistryVariables(surface) {
+    if (surface.variables.length === 0) {
+        return;
+    }
+    const names = surface.variables.map((variable) => variable.name).join(", ");
+    throw new ImportValidationError(`this surface is templated on ${names} (${surface.variables
+        .map((variable) => variable.resolveFrom ?? variable.name)
+        .join("; ")}) — per-tenant URL variables are not supported; paste a resolved spec or endpoint URL instead`);
+}
+// ---------------------------------------------------------------------------
+// Fetch + normalize
+// ---------------------------------------------------------------------------
+export async function fetchSpecText(url, fetchImpl = createGuardedFetch()) {
+    return await fetchTextBounded({
+        fetchImpl,
+        headers: { accept: "application/json, application/yaml, text/yaml, */*" },
+        maxBytes: MAX_SPEC_BYTES,
+        signal: AbortSignal.timeout(SPEC_FETCH_TIMEOUT_MS),
+        url,
+    });
+}
+/** Registry surface whose MCP/API calls need a credential. */
+export function surfaceRequiresAuth(surface) {
+    return surface?.auth.status === "required";
+}
+function emptyMcpNormalize() {
+    return {
+        actions: [],
+        applied_overrides: 0,
+        base_url: null,
+        description: null,
+        dropped_count: 0,
+        security_schemes: null,
+        skipped: [],
+        title: null,
+    };
+}
+export function deferredMcpPrepared(sourceUrl) {
+    return {
+        deferred_mcp_tools: true,
+        normalized: emptyMcpNormalize(),
+        spec_hash: createHash("sha256")
+            .update(`deferred-mcp:${sourceUrl}`)
+            .digest("hex"),
+    };
+}
+/** Fetch + normalize one source. openapi → spec text; mcp → live tools/list. */
+export async function prepareSource(params) {
+    const fetchImpl = params.fetchImpl ?? createGuardedFetch();
+    const overrides = params.specOverrides ?? [];
+    if (params.sourceKind === "openapi") {
+        const specText = await fetchSpecText(params.sourceUrl, fetchImpl);
+        const normalized = await normalizeOpenApiSpec(specText, {
+            specOverrides: overrides,
+        });
+        return {
+            normalized,
+            // Overrides are part of what was imported: a changed patch must show up
+            // as a changed spec hash on refresh.
+            spec_hash: createHash("sha256")
+                .update(specText)
+                .update(JSON.stringify(overrides))
+                .digest("hex"),
+        };
+    }
+    if (params.deferMcpTools) {
+        return deferredMcpPrepared(params.sourceUrl);
+    }
+    try {
+        const normalized = await normalizeMcpServer({
+            endpoint: params.sourceUrl,
+            fetchImpl,
+            headers: {
+                ...headersFromRequired(params.requiredHeaders ?? []),
+                ...params.mcpHeaders,
+            },
+            transport: params.transport ?? null,
+        });
+        return {
+            normalized,
+            spec_hash: createHash("sha256")
+                .update(JSON.stringify(normalized.actions))
+                .digest("hex"),
+        };
+    }
+    catch (error) {
+        if ((params.deferOnUnauthorized ?? true) && isUnauthorizedMcpError(error)) {
+            return deferredMcpPrepared(params.sourceUrl);
+        }
+        throw error;
+    }
+}
+/** Stored required headers as a request header map. */
+export function headersFromRequired(headers) {
+    const out = {};
+    for (const header of headers) {
+        out[header.name] = header.value;
+    }
+    return out;
+}
+export function assembleRecord(params) {
+    validateConnectorNaming({
+        id: params.id,
+        tenantId: params.tenantId,
+        toolPrefix: params.toolPrefix,
+    });
+    const { normalized } = params.prepared;
+    const warnings = [];
+    const surface = params.surface ?? null;
+    if (surface) {
+        assertNoRegistryVariables(surface);
+    }
+    const requiredHeaders = surface ? resolveRequiredHeaders(surface) : [];
+    const mapped = mapAuth({
+        discover: params.discover ?? null,
+        securitySchemes: normalized.security_schemes,
+        sourceKind: params.sourceKind,
+        surface,
+    });
+    if (!mapped.ok) {
+        throw new ImportValidationError(mapped.reason);
+    }
+    const auth = mapped.auth;
+    if (auth.kind === "oauth2" && !params.oauthClient) {
+        if (auth.dcr && auth.registration_endpoint) {
+            warnings.push("oauth2 client will be registered on first authenticate (dynamic client registration)");
+        }
+        else {
+            warnings.push("oauth2 connector imported without client credentials — connects will fail until they are set");
+        }
+    }
+    const filter = params.actionFilter?.length
+        ? new Set(params.actionFilter)
+        : null;
+    const actions = filter
+        ? normalized.actions.filter((action) => filter.has(action.id))
+        : normalized.actions;
+    const deferredMcp = params.prepared.deferred_mcp_tools === true && params.sourceKind === "mcp";
+    if (actions.length === 0 && !deferredMcp) {
+        throw new ImportValidationError("no importable actions (empty spec, all filtered out, or all skipped)");
+    }
+    if (deferredMcp) {
+        warnings.push("tools load once an account is connected");
+    }
+    if (normalized.dropped_count > 0) {
+        warnings.push(`${normalized.dropped_count} operation(s) dropped by the per-connector cap`);
+    }
+    if (normalized.skipped.length > 0) {
+        warnings.push(`${normalized.skipped.length} operation(s) skipped: ${normalized.skipped
+            .slice(0, 5)
+            .map((s) => `${s.id} (${s.reason})`)
+            .join(", ")}${normalized.skipped.length > 5 ? ", …" : ""}`);
+    }
+    if (normalized.applied_overrides > 0) {
+        warnings.push(`${normalized.applied_overrides} registry spec override(s) applied before normalization`);
+    }
+    const baseUrl = params.baseUrlOverride ?? normalized.base_url ?? null;
+    if (params.sourceKind === "openapi" && !baseUrl) {
+        throw new ImportValidationError("spec declares no server URL — provide base_url explicitly");
+    }
+    const record = {
+        actions,
+        auth_config: auth,
+        base_url: baseUrl,
+        client_id_enc: params.oauthClient
+            ? encryptToken(params.oauthClient.clientId)
+            : null,
+        client_secret_enc: params.oauthClient
+            ? encryptToken(params.oauthClient.clientSecret)
+            : null,
+        domain: params.domain,
+        id: params.id,
+        imported_at: new Date().toISOString(),
+        imported_by: params.importedBy,
+        mcp_transport: params.sourceKind === "mcp"
+            ? ((surface ? resolveMcpTransport(surface) : null) ?? "streamable-http")
+            : null,
+        name: params.name ?? normalized.title ?? surface?.name ?? params.domain,
+        refreshed_at: null,
+        registry_snapshot: params.rawDiscover ?? null,
+        registry_surface_slug: surface?.slug ?? null,
+        required_headers: requiredHeaders,
+        source_kind: params.sourceKind,
+        source_url: params.sourceUrl,
+        spec_hash: params.prepared.spec_hash,
+        status: "enabled",
+        tenant_id: params.tenantId,
+        tool_prefix: params.toolPrefix,
+    };
+    return { record, warnings };
+}

package/apps/runtime/dist/engenty/connections-external/importer/classify.js

@@ -0,0 +1,34 @@
+/**
+ * Map an HTTP method (plus path hints) onto the connections-framework action
+ * groups. Groups drive default policy (read→allow, write/destructive→ask) and
+ * the approval contract, so lean conservative: anything ambiguous is `write`,
+ * clearly irreversible verbs are `destructive`.
+ */
+const DESTRUCTIVE_PATH_HINT = /\b(delete|remove|destroy|purge|revoke|cancel|terminate)\b/iu;
+export function classifyHttpOperation(method, pathTemplate) {
+    const m = method.toLowerCase();
+    if (m === "get" || m === "head" || m === "options") {
+        return "read";
+    }
+    if (m === "delete") {
+        return "destructive";
+    }
+    if (DESTRUCTIVE_PATH_HINT.test(pathTemplate)) {
+        return "destructive";
+    }
+    return "write";
+}
+/**
+ * MCP tool annotations → classification. `readOnlyHint` is trusted for reads;
+ * `destructiveHint` for destructive; everything else defaults to `write`
+ * (server-provided hints are advisory, so no hint never yields `read`).
+ */
+export function classifyMcpTool(annotations) {
+    if (annotations.readOnlyHint === true) {
+        return "read";
+    }
+    if (annotations.destructiveHint === true) {
+        return "destructive";
+    }
+    return "write";
+}

package/apps/runtime/dist/engenty/connections-external/importer/map-auth.js

@@ -0,0 +1,185 @@
+import { discoverOAuthFacts, } from "../registry-client.js";
+/** Map an OpenAPI 3.x securitySchemes object (spec wins over registry facts). */
+export function mapAuthFromSecuritySchemes(schemes) {
+    const entries = Object.entries(schemes);
+    // Prefer a static API key / bearer when the spec also advertises OAuth —
+    // personal access tokens work without an admin-registered developer app.
+    // Figma REST is the canonical case (PersonalAccessToken + OAuth2).
+    const bearer = entries.find(([, s]) => s.type === "http" && s.scheme?.toLowerCase() === "bearer");
+    if (bearer) {
+        return {
+            fields: [
+                { key: "api_token", label: "API token", required: true, secret: true },
+            ],
+            kind: "api_key",
+            placement: {
+                in: "header",
+                name: "Authorization",
+                value_template: "Bearer {{api_token}}",
+            },
+        };
+    }
+    const apiKey = entries.find(([, s]) => s.type === "apiKey" && (s.in === "header" || s.in === "query"));
+    if (apiKey) {
+        const scheme = apiKey[1];
+        return {
+            fields: [
+                { key: "api_key", label: "API key", required: true, secret: true },
+            ],
+            kind: "api_key",
+            placement: {
+                in: scheme.in === "query" ? "query" : "header",
+                name: scheme.name ?? "X-API-Key",
+                value_template: "{{api_key}}",
+            },
+        };
+    }
+    const oauth = entries.find(([, s]) => s.type === "oauth2" && s.flows?.authorizationCode);
+    if (oauth) {
+        const flow = oauth[1].flows?.authorizationCode;
+        if (flow?.authorizationUrl && flow.tokenUrl) {
+            return {
+                auth_url: flow.authorizationUrl,
+                kind: "oauth2",
+                scopes: Object.keys(flow.scopes ?? {}),
+                token_url: flow.tokenUrl,
+            };
+        }
+    }
+    return null;
+}
+/** Fallback: map the domain's discovered OAuth facts. */
+export function mapAuthFromRegistry(discover) {
+    const oauth = discoverOAuthFacts(discover);
+    if (oauth?.authorizationEndpoint &&
+        oauth.tokenEndpoint &&
+        (oauth.grantTypes.length === 0 ||
+            oauth.grantTypes.includes("authorization_code"))) {
+        const dcr = oauth.dcr === true && Boolean(oauth.registrationEndpoint?.trim());
+        return {
+            auth_url: oauth.authorizationEndpoint,
+            kind: "oauth2",
+            scopes: oauth.scopes,
+            token_url: oauth.tokenEndpoint,
+            ...(dcr
+                ? {
+                    dcr: true,
+                    registration_endpoint: oauth.registrationEndpoint,
+                }
+                : {}),
+        };
+    }
+    return null;
+}
+/** A credential id reduced to a stored field key. */
+function fieldKey(credentialId) {
+    const key = credentialId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 40);
+    return key || "api_key";
+}
+/** Whether a mechanic describes an OAuth flow rather than a static credential. */
+function isOauthMechanics(mechanics) {
+    if (mechanics.source === "well-known") {
+        return true;
+    }
+    return (mechanics.source === "spec" &&
+        (mechanics.scheme ?? "").toLowerCase().includes("oauth"));
+}
+/**
+ * Map one registry auth alternative. Returns null when this alternative is not
+ * expressible — the caller tries the next one before giving up.
+ */
+function mapSurfaceAuthEntry(params) {
+    const { entry } = params;
+    if (entry.use.length === 0) {
+        return null;
+    }
+    if (entry.use.length === 1 && isOauthMechanics(entry.use[0].mechanics)) {
+        return params.discover ? mapAuthFromRegistry(params.discover) : null;
+    }
+    // A single header/query credential is the only static placement the stored
+    // config can express; multi-credential alternatives (client id + secret
+    // headers) have no single placement and fall through to the next entry.
+    if (entry.use.length !== 1) {
+        return null;
+    }
+    const { id, mechanics } = entry.use[0];
+    if (mechanics.source !== "http") {
+        return null;
+    }
+    const placementIn = mechanics.in === "query" ? "query" : "header";
+    const name = mechanics.headerName ?? (placementIn === "query" ? "api_key" : "X-API-Key");
+    if (placementIn === "header" && !mechanics.headerName) {
+        return null;
+    }
+    const key = fieldKey(id);
+    const scheme = mechanics.scheme?.trim();
+    return {
+        fields: [
+            {
+                key,
+                label: params.credentialLabel(id),
+                required: true,
+                secret: true,
+            },
+        ],
+        kind: "api_key",
+        placement: {
+            in: placementIn,
+            name,
+            value_template: scheme ? `${scheme} {{${key}}}` : `{{${key}}}`,
+        },
+    };
+}
+/** Human-readable summary of what the registry said, for reject reasons. */
+function describeSurfaceAuth(surface) {
+    if (surface.auth.entries.length === 0) {
+        return `auth status "${surface.auth.status}" with no credential facts`;
+    }
+    const shapes = surface.auth.entries.map((entry) => entry.use.map((use) => `${use.id} via ${use.mechanics.source}`).join(" + "));
+    return `alternatives: ${shapes.join("; ")}`;
+}
+export function mapAuth(params) {
+    const surface = params.surface ?? null;
+    if (surface?.auth.status === "none") {
+        return { auth: { kind: "none" }, ok: true };
+    }
+    if (params.securitySchemes) {
+        const fromSpec = mapAuthFromSecuritySchemes(params.securitySchemes);
+        if (fromSpec) {
+            return { auth: fromSpec, ok: true };
+        }
+    }
+    if (surface) {
+        const credentials = params.discover?.credentials ?? {};
+        const credentialLabel = (id) => credentials[id]?.label ?? "API credential";
+        for (const entry of surface.auth.entries) {
+            const mapped = mapSurfaceAuthEntry({
+                credentialLabel,
+                discover: params.discover ?? null,
+                entry,
+            });
+            if (mapped) {
+                return { auth: mapped, ok: true };
+            }
+        }
+    }
+    if (params.discover) {
+        const fromRegistry = mapAuthFromRegistry(params.discover);
+        if (fromRegistry) {
+            return { auth: fromRegistry, ok: true };
+        }
+    }
+    const found = surface
+        ? describeSurfaceAuth(surface)
+        : params.sourceKind === "openapi"
+            ? "no usable securitySchemes in the spec"
+            : "no registry auth facts for this endpoint";
+    return {
+        ok: false,
+        reason: `cannot map authentication (${found}) — supported: no auth, OAuth 2 authorization_code, or a single header/query API key`,
+    };
+}