@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/agent-mcp/types.ts

@@ -0,0 +1,138 @@
+/**
+ * The shapes the harness passes around. No behaviour, so every other file here can import
+ * it without importing anything else.
+ */
+
+/**
+ * AGENT MCP HARNESS — the model-agnostic half of a conversational agent's tool loop.
+ *
+ * Every agent family (OpenAI, GLM, Grok, …) shares the SAME platform behavior:
+ *   - which spatial-search results become callable tools (node-MCP rows + Unoverse
+ *     app rows carrying the manifest call contract),
+ *   - how an interactive APP tool presents itself to the model (the etiquette lives
+ *     in the tool DESCRIPTION — the only channel that reaches a model for a tool
+ *     minted MID-conversation; instructions are built once at loop start),
+ *   - when a tool call ENDS the agent's turn (provenance + result shape, never a
+ *     hardcoded name list).
+ *
+ * This module is that behavior, once — `@unoverse-platform/base/agent-mcp`.
+ * Agent families keep only their streaming adapters (wire shapes, chunk handling,
+ * token accounting) and map their tool-call objects into `AgentToolExchange` to
+ * consume it. Fixes land here and reach every family — the previous state
+ * (openai-only, GLM unable to discover apps at all, Grok forked) is exactly what
+ * this exists to prevent. A conformance guard fails the build if an agent family
+ * re-implements this logic instead of importing it.
+ *
+ * THE ONE-WIRE-CALL RULE — where our code ends and native MCP begins. Everything here
+ * is pure interpretation/routing and never touches the MCP wire, EXCEPT
+ * `invokeComponentAppNative` — the single function that opens an MCP client and makes a
+ * real `tools/call`. From that call onward it is all native MCP (the server renders +
+ * elicits; the answers resolve the call). Node-MCP rows and path-A workflow apps route
+ * in-process via the caller's `api.callService` because they have a node/workflow to run;
+ * only path-B component apps (nothing local to call) ride the wire. Full map:
+ * docs/MCP_COMPLETE_GUIDE.md → "where YOUR code ends and native MCP begins".
+ */
+
+/** One executed tool call, reduced to what the harness needs: its name and the
+ *  raw result content string the model will see. */
+export interface AgentToolExchange {
+  name: string;
+  resultContent: string;
+}
+
+/** A spatial-discovered MCP, normalized: node-MCP rows and Unoverse app rows both
+ *  come out in this shape, ready to mint as a model tool via `toolDefFromDiscoveredMCP`. */
+export interface DiscoveredMCP {
+  id: string;
+  title: string;
+  description: string;
+  workflowId: string;
+  nodeId: string;
+  methodName: string;
+  /** Full method schema ({ methods: { [name]: { description, input } } }). */
+  schema?: any;
+  /**
+   * PATH B (UNOVERSE_MCP_APP_PROTOCOL §0.1 / §4b): a self-contained component app —
+   * an `app` URI but NO workflow. Holds the app-tool id the adapter hands to
+   * `invokeComponentAppNative` (the held native `/mcp` call) instead of firing
+   * `workflow@trigger`; `workflowId`/`nodeId` are empty. Undefined for node-MCP + path-A apps.
+   */
+  component?: string;
+  /** PATH B: the app's resource URI (`unoverse://components/[<org>/]<name>`) — the ONLY
+   *  schema handle. The tool's input schema is read LIVE from `<appUri>/schema` at mint
+   *  time (`resolveToolDefNative`); spatial rows carry no schema copy. */
+  appUri?: string;
+}
+
+/** A neutral function-tool definition; each family maps this to its wire format. */
+export interface AgentToolDef {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+/** Mint the model-facing tool definition for a discovered MCP. */
+
+/** Context a held app call needs to reach the human on the live session. */
+export interface AppInvocationContext {
+  /** The caller's stream session — where the wizard renders and elicitation is answered. */
+  conversationId?: string;
+  userId?: string;
+  /** The current TURN id — the component renders in this turn's bubble. */
+  chatId?: string;
+  /** Seeds the elicitation prompt; the app tool schema requires the field (may be ""). */
+  message?: string;
+  /** Content-tree app rows: the row's content, seeded as-is into the component's state. */
+  props?: Record<string, unknown>;
+  /** Content-tree app rows: the ROW id — keys the render `<component>:<instanceId>` so multiple rows sharing a component don't collide. */
+  instanceId?: string;
+  /** These props are ROW DATA, not a model's composition — skip the brief referee. */
+  fromRow?: boolean;
+  /** Deliver the component's SHELL only: render it in its declared state and return
+   *  at once — never collect its outputs (§12e "Discovery delivers; it never invokes"). */
+  shell?: boolean;
+  /** The delivery batch this render belongs to (UNOVERSE_TEMPLATE_MODEL §12e): the
+   *  server's director judges the WHOLE batch before anything renders. `size` is how
+   *  many siblings to wait for; `index` is this render's arrival position. */
+  batch?: { id: string; size: number; index: number };
+  /** Forwarded as a Bearer token so the internal `/mcp` call rides the gated lane too. */
+  accessToken?: string;
+  /** Internal MCP base; defaults to UNOVERSE_SERVICE_URL or http://localhost:4106. */
+  baseUrl?: string;
+}
+
+/**
+ * NATIVE MCP APP INVOCATION (UNOVERSE_MCP_APP_PROTOCOL §3.3 / §4b) — the held
+ * slow-call that renders a component app and returns the user's submitted answers to
+ * the CALLING model.
+ *
+ * A bindingless component app has no workflow to fire. Calling it is ONE held
+ * `tools/call` to the platform's internal MCP server (`/mcp`): the server registered the
+ * app as a tool (mcpServer `listApps()`), renders the component on the caller's live
+ * session and ELICITS its declared `outputs` block, then resolves the call with
+ * `{ output }`. No polling and no timeout by design — an abandoned form is a tool call
+ * that never returns (the SDK's 60s default is lifted to 24h). The answers come back as
+ * the tool result so the model continues in-turn.
+ *
+ * This is the modern replacement for the legacy engine's
+ * `MCPInvoker.awaitAppOutputNative`: same native slow-call, but driven from this shared
+ * harness (every agent family) using the app id it parsed at mint time — so it needs NO
+ * server-side (XState) schema cache.
+ */
+/** Open an MCP client on the platform's internal `/mcp` — the ONE wire-connect shared by
+ *  every native call this harness makes (app invocation, live schema read). */
+
+/** A content-tree row's attached COMPONENT, ready to render — see rowComponentsFromResults. */
+export interface RowComponent {
+  /** The row's identity — dedupe key (one render per row, ever). */
+  id: string;
+  /** The component app-tool id (`unoverse://components/<id>` → `<id>`). */
+  component: string;
+  /** The row's content AS-IS — the component's state (binds resolve by name). */
+  props: Record<string, unknown>;
+  /** A SHELL delivery (TEMPLATE_MODEL §12e "One ladder, one delivery"): the row is a
+   *  component that takes input (a manifest, no workflow). It arrives in the same
+   *  delivery as the cards, in its declared state, with its own defaults and NO row
+   *  props; it is never invoked here — its form opens only on the model's call. */
+  shell?: boolean;
+}

package/vendor/base/src/auth/auth.ts

@@ -0,0 +1,307 @@
+/**
+ * JWT authentication for the Unoverse MCP server.
+ *
+ * Mirrors apps/mcp-server/src/server/auth/auth.ts — same OIDC/JWT flow as the rest
+ * of the platform (docs/AUTH_TOKEN_FLOW.md): validate the access token against the
+ * shared AUTH_ISSUER/AUTH_AUDIENCE via JWKS. The only difference is transport: this
+ * server speaks MCP over uWS + Web `Request`/`Response`, so the gate is a pure
+ * function over the Authorization header rather than node req/res.
+ *
+ * Secure-MCP per the MCP best-practices/authorization specs: default-deny, 401 +
+ * `WWW-Authenticate` pointing at RFC 9728 protected-resource-metadata.
+ */
+
+import { jwtVerify, createRemoteJWKSet, JWTPayload } from "jose";
+import { isAuthEnabled, devIdentity } from "./authConfig.js";
+
+// Read env lazily (not at module load) so it's correct regardless of when .env loads.
+//
+// THE ISSUER SPELLING IS PROVIDER-SPECIFIC AND jose COMPARES `iss` EXACTLY.
+//
+// Auth0 mints `iss` WITH a trailing slash; Cognito mints it WITHOUT one (verified against
+// the pool's own discovery document: issuer =
+// https://cognito-idp.<region>.amazonaws.com/<poolId>, no slash). This used to append a
+// slash unconditionally, which matches Auth0 and can therefore NEVER match Cognito: every
+// authenticated request on an AWS universe failed with `unexpected "iss" claim value` while
+// sign-in, the pool, the client and the token were all correct (BPP, 2026-08-17).
+//
+// So accept BOTH spellings of the one configured issuer rather than one provider's
+// convention. This is the same shape as the `aud`/`client_id` comparison below: it looks in
+// two places, it does not accept fewer. A token from any other issuer is rejected exactly as
+// before, because both candidates are built from AUTH_ISSUER itself.
+const getIssuerBase = (): string => {
+  const raw = process.env.AUTH_ISSUER;
+  if (!raw || raw === "undefined") return "";
+  return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+};
+/** Both spellings of the configured issuer, for jose's exact `iss` comparison. */
+const getIssuerCandidates = (): string[] => {
+  const base = getIssuerBase();
+  return base ? [base, `${base}/`] : [];
+};
+const getAudience = (): string | undefined => process.env.AUTH_AUDIENCE;
+
+let jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
+function getJWKS() {
+  const base = getIssuerBase();
+  if (!jwks && base) {
+    jwks = createRemoteJWKSet(new URL(`${base}/.well-known/jwks.json`));
+  }
+  return jwks;
+}
+
+export interface AuthUser {
+  id: string;
+  email?: string;
+  roles: string[];
+  permissions: string[];
+  raw: JWTPayload;
+}
+
+/** Parse array claims, handling Auth0-style namespaced claims (e.g. https://…/roles). */
+function parseArrayClaim(payload: JWTPayload, claimName: string): string[] {
+  const direct = payload[claimName];
+  if (Array.isArray(direct)) return direct as string[];
+  const namespaced = Object.keys(payload).find(
+    (k) => k.endsWith(`/${claimName}`) || k.endsWith(`/claims/${claimName}`),
+  );
+  if (namespaced && Array.isArray(payload[namespaced])) return payload[namespaced] as string[];
+  return [];
+}
+
+/** Parse a string claim, handling Auth0-style namespaced claims (e.g. https://…/email).
+ *  Auth0 emits custom claims (email on the access token) ONLY namespaced, so a plain
+ *  `payload.email` read returns undefined and silently no-ops every email-keyed feature
+ *  (CRM resolve). Same namespace-aware read as parseArrayClaim. See docs/AUTH_TOKEN_FLOW.md. */
+function parseStringClaim(payload: JWTPayload, claimName: string): string | undefined {
+  const direct = payload[claimName];
+  if (typeof direct === "string") return direct;
+  const namespaced = Object.keys(payload).find(
+    (k) => k.endsWith(`/${claimName}`) || k.endsWith(`/claims/${claimName}`),
+  );
+  if (namespaced && typeof payload[namespaced] === "string") return payload[namespaced] as string;
+  return undefined;
+}
+
+/**
+ * VERIFIED TOKENS, REMEMBERED UNTIL THEY EXPIRE. A token is immutable: the same string
+ * verifies to the same user every time until `exp`, and nothing here checks revocation
+ * on the way (it never did). Yet every request on /mcp, /stream, /api/* and every
+ * per-click user_action paid a full RS256 verify, and the proxy and trigger paths paid
+ * it TWICE (gate, then enrichment). Bounded and insertion-evicted; an entry is trusted
+ * only while `now < exp`, so an expired token is re-verified and refused exactly as
+ * before. The JWKS fetch was already cached by jose; this caches the verify.
+ */
+const VERIFIED_MAX = 1000;
+/** Cache life for a token that carries no `exp` (jose still verified it). */
+const VERIFIED_NO_EXP_MS = 60_000;
+const verified = new Map<string, { user: AuthUser; until: number }>();
+
+/** Validate a bearer token and extract the user, or null if invalid/unconfigured. */
+export async function validateJWT(token: string): Promise<AuthUser | null> {
+  const hit = verified.get(token);
+  if (hit) {
+    if (Date.now() < hit.until) return hit.user;
+    verified.delete(token);
+  }
+  const user = await verifyJWT(token);
+  if (user) {
+    const exp = typeof user.raw.exp === "number" ? user.raw.exp * 1000 : Date.now() + VERIFIED_NO_EXP_MS;
+    if (verified.size >= VERIFIED_MAX) verified.delete(verified.keys().next().value as string);
+    verified.set(token, { user, until: exp });
+  }
+  return user;
+}
+
+async function verifyJWT(token: string): Promise<AuthUser | null> {
+  const jwksSet = getJWKS();
+  const issuers = getIssuerCandidates();
+  if (!jwksSet || issuers.length === 0) {
+    console.warn("[auth] OIDC not configured (AUTH_ISSUER missing)");
+    return null;
+  }
+  try {
+    // AUDIENCE IS CHECKED HERE, NOT BY jose, BECAUSE PROVIDERS NAME IT DIFFERENTLY.
+    //
+    // Auth0 access tokens carry the API identifier in `aud`. Cognito access tokens have NO
+    // `aud` at all — the same value lives in `client_id`, and `aud` appears only on its ID
+    // tokens. Verified 2026-08-03 against a real token: {iss, client_id, token_use:"access",
+    // ...} with no aud. So `jwtVerify(..., { audience })` can never pass on AWS, and every
+    // authenticated request there failed with `missing required "aud" claim` on a
+    // deployment that was otherwise entirely correct.
+    //
+    // Signature, issuer and expiry are still jose's and unchanged. Only the comparison moves
+    // out, so it can read whichever claim the provider used. A token matching neither is
+    // rejected exactly as before — this looks in two places, it does not accept fewer.
+    const { payload } = await jwtVerify(token, jwksSet, { issuer: issuers });
+    const expected = getAudience();
+    if (expected) {
+      const claimed = payload.aud ?? (payload as Record<string, unknown>).client_id;
+      const values = Array.isArray(claimed) ? claimed.map(String) : claimed ? [String(claimed)] : [];
+      if (!values.includes(expected)) {
+        console.error(
+          `[auth] JWT validation failed: audience mismatch (expected ${expected}, token had ${values.join(", ") || "none"})`,
+        );
+        return null;
+      }
+    }
+    return {
+      id: payload.sub || "unknown",
+      email: parseStringClaim(payload, "email"),
+      roles: parseArrayClaim(payload, "roles"),
+      permissions: parseArrayClaim(payload, "permissions"),
+      raw: payload,
+    };
+  } catch (error) {
+    console.error("[auth] JWT validation failed:", error);
+    return null;
+  }
+}
+
+export type AuthResult = { ok: true; userId: string } | { ok: false };
+
+/**
+ * Default-deny gate over the Authorization header.
+ *  - auth DISABLED (dev) → pass as the fixed dev identity (never undefined).
+ *  - auth ENABLED → require a valid bearer for AUTH_ISSUER/AUTH_AUDIENCE.
+ */
+export async function authorize(authHeader: string | null | undefined): Promise<AuthResult> {
+  if (!isAuthEnabled()) return { ok: true, userId: devIdentity().id };
+  if (!authHeader) return { ok: false };
+  const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+  if (!token) return { ok: false };
+  const user = await validateJWT(token);
+  return user ? { ok: true, userId: user.id } : { ok: false };
+}
+
+/**
+ * The permission a token must carry to reach the HOSTED workflow builder. Gated on
+ * this exact string (Auth0 API permission on the gravity-api audience), NOT on a
+ * role name — end-user chat tokens are valid on the same audience, so "authenticated"
+ * is not enough; only "authenticated AND may author workflows" passes. This is the
+ * platform's first authZ check (docs/AUTH_REMEDIATION.md Phase 1b).
+ */
+export const BUILDER_PERMISSION = "workflow:author";
+
+export type BuilderAuthResult = { ok: true; user: AuthUser } | { ok: false; reason: "unauthenticated" | "forbidden" };
+
+/**
+ * Gate for the hosted builder route (public :4105/mcp-builder). Stricter than
+ * `authorize` in two ways:
+ *  - FAIL-CLOSED when auth is disabled: this route must never be open, so an
+ *    AUTH_ENABLED=false deployment simply cannot serve it (returns forbidden).
+ *    Local dev uses the ungated LOOPBACK route (:4106) instead — never this one.
+ *  - Requires the BUILDER_PERMISSION claim, not just a valid bearer.
+ * Returns the full user so a later step can bind the session to a workflow grant.
+ */
+export async function authorizeBuilder(authHeader: string | null | undefined): Promise<BuilderAuthResult> {
+  // No fail-open: unlike `authorize`, disabled auth does NOT admit a dev identity here.
+  if (!isAuthEnabled()) return { ok: false, reason: "forbidden" };
+  if (!authHeader) return { ok: false, reason: "unauthenticated" };
+  const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+  if (!token) return { ok: false, reason: "unauthenticated" };
+  const user = await validateJWT(token);
+  if (!user) return { ok: false, reason: "unauthenticated" };
+  if (!user.permissions.includes(BUILDER_PERMISSION)) return { ok: false, reason: "forbidden" };
+  return { ok: true, user };
+}
+
+/**
+ * NO ADMIN GATE HERE, DELIBERATELY. `ADMIN_ROLE` and `authorizeAdmin` lived at this spot for
+ * one day. They were the right fix for the credential store and the wrong shape for the
+ * platform: a second bespoke gate beside `authorizeBuilder`, which is how five modules ended
+ * up holding five different answers to one question.
+ *
+ * Authorization now lives in ONE place — `apps/unoverse/server/src/security/` — where a
+ * table names every route's requirement and one function reads it. This module keeps what is
+ * genuinely shared: token validation, the builder gate that predates the table, and the
+ * discovery metadata. See security/policy.ts.
+ */
+
+/**
+ * Public base URL for advertised OAuth metadata. Prefer the configured canonical URL
+ * (UNOVERSE_PUBLIC_URL) over the request `Host` header — the header is client-controlled,
+ * so reflecting it into discovery metadata is a (minor) spoofing vector.
+ */
+function resourceBase(host: string): string {
+  const configured = process.env.UNOVERSE_PUBLIC_URL?.replace(/\/$/, "");
+  if (configured) return configured;
+  const protocol = host.includes("localhost") || host.startsWith("127.") ? "http" : "https";
+  return `${protocol}://${host}`;
+}
+
+/** The 401 challenge — points clients at the RFC 9728 protected-resource-metadata. */
+export function unauthorizedResponse(host: string): Response {
+  const resourceMetadataUrl = `${resourceBase(host)}/.well-known/oauth-protected-resource`;
+  return new Response(
+    JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message: "Unauthorized" }, id: null }),
+    {
+      status: 401,
+      headers: {
+        "content-type": "application/json",
+        "WWW-Authenticate": `Bearer resource_metadata="${resourceMetadataUrl}"`,
+      },
+    },
+  );
+}
+
+/** OAuth Authorization Server Metadata (for MCP Inspector / discovery). */
+export function getOAuthAuthorizationServerMetadata(): object {
+  const issuer = process.env.AUTH_ISSUER;
+  const audience = process.env.AUTH_AUDIENCE;
+  return {
+    issuer,
+    authorization_endpoint: audience
+      ? `${issuer}/authorize?audience=${encodeURIComponent(audience)}`
+      : `${issuer}/authorize`,
+    token_endpoint: `${issuer}/oauth/token`,
+    registration_endpoint: `${issuer}/oidc/register`,
+    scopes_supported: ["openid", "profile", "email", "offline_access"],
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    code_challenge_methods_supported: ["S256"],
+  };
+}
+
+/**
+ * What a REMOTE client needs to log in to this universe, served publicly.
+ *
+ * Canvas gets this from `window.__GRAVITY_CONFIG__`, injected into its own page
+ * (`apps/canvas/src/App.jsx:14`). A developer's local Studio is a different origin on a
+ * different machine, so it cannot read that. It has to ask the universe.
+ *
+ * This is the whole reason the tooling stays provider-agnostic: Studio hardcodes no
+ * issuer and no provider. It asks a universe who authenticates it and follows the answer,
+ * so Auth0, Okta, Entra or Keycloak all work with no change here or in Studio.
+ *
+ * NOTHING SECRET. `clientId` is a public OAuth client identifier by definition, it is
+ * already shipped inside Canvas's JavaScript, and it authorises nothing on its own.
+ * There is deliberately no client secret: a desktop tool cannot keep one.
+ *
+ * `authEnabled: false` is a real answer, not a failure. A universe with auth off tells a
+ * client not to bother logging in, rather than sending it to an issuer that is not there.
+ */
+export function getPublicAuthConfig(): object {
+  const issuer = process.env.AUTH_ISSUER;
+  const clientId = process.env.AUTH_CLIENT_ID;
+  return {
+    authEnabled: isAuthEnabled(),
+    issuer: issuer ?? null,
+    clientId: clientId ?? null,
+    audience: process.env.AUTH_AUDIENCE ?? null,
+    // The permission a developer's token needs before this universe will accept a
+    // publish. Named here so Studio can say "you are logged in but not allowed to
+    // publish" instead of failing at the first push.
+    publishPermission: "marketplace:publish",
+  };
+}
+
+/** OAuth 2.0 Protected Resource Metadata (RFC 9728); canonical URL preferred over Host. */
+export function getOAuthProtectedResourceMetadata(host: string): object {
+  return {
+    resource: resourceBase(host),
+    authorization_servers: [process.env.AUTH_ISSUER],
+    scopes_supported: ["openid", "profile", "email"],
+    bearer_methods_supported: ["header"],
+  };
+}

package/vendor/base/src/auth/authConfig.ts

@@ -0,0 +1,73 @@
+/**
+ * Canonical auth flag + startup contract.
+ *
+ * MIRRORED across services (apps/server, apps/mcp-server, apps/memory-server, and
+ * now apps/unoverse) — keep the copies in sync. Single source of truth:
+ * docs/AUTH_REMEDIATION.md (Phase 0).
+ *
+ * Rules:
+ *  - Default: auth ENABLED. Only an explicit AUTH_ENABLED=false (or the deprecated
+ *    DISABLE_AUTH=true) turns it off. Missing/typo'd flags read as ENABLED.
+ *  - "Not configured" is NOT "disabled": if auth is enabled but OIDC is missing,
+ *    the service refuses to boot (assertAuthStartup) rather than silently allow.
+ *  - Disabled: a fixed dev identity is injected so downstream code always has auth.
+ *  - Disabled + NODE_ENV=production: refuse to boot.
+ */
+
+export interface DevIdentity {
+  id: string;
+  email: string;
+  roles: string[];
+  permissions: string[];
+}
+
+const isTrue = (v: string | undefined): boolean => v?.toLowerCase() === "true";
+
+/** Single source of truth: is JWT enforcement on? Default ON; only explicit opt-out disables. */
+export function isAuthEnabled(): boolean {
+  if (isTrue(process.env.DISABLE_AUTH)) return false; // deprecated alias, still honored
+  return (process.env.AUTH_ENABLED ?? "true").toLowerCase() !== "false";
+}
+
+/** Is an OIDC provider configured (issuer + audience present)? */
+export function isOidcConfigured(): boolean {
+  const issuer = process.env.AUTH_ISSUER;
+  return !!issuer && issuer !== "undefined" && !!process.env.AUTH_AUDIENCE;
+}
+
+/** Fixed identity injected on every request when auth is DISABLED (dev only).
+ *  Deliberately carries NO roles and NO permissions: any gate accidentally built on
+ *  `authorize()` instead of a fail-closed wrapper then denies rather than escalates. */
+export function devIdentity(): DevIdentity {
+  return { id: "dev-user", email: "dev@local", roles: [], permissions: [] };
+}
+
+/**
+ * Validate auth configuration at boot. Fails closed:
+ *  - enabled + OIDC missing → throw (refuse to start)
+ *  - disabled + production  → throw (refuse to start)
+ * Returns the resolved mode and logs the true state.
+ */
+export function assertAuthStartup(log: (msg: string) => void = console.warn): "enabled" | "disabled" {
+  const enabled = isAuthEnabled();
+  const isProd = process.env.NODE_ENV === "production";
+
+  if (enabled && !isOidcConfigured()) {
+    throw new Error(
+      "[auth] Auth is ENABLED but OIDC is not configured (AUTH_ISSUER/AUTH_AUDIENCE missing). " +
+        "Refusing to start. For local dev without auth, set AUTH_ENABLED=false.",
+    );
+  }
+  if (!enabled && isProd) {
+    throw new Error(
+      "[auth] Auth is DISABLED (AUTH_ENABLED=false / DISABLE_AUTH=true) while NODE_ENV=production. Refusing to start.",
+    );
+  }
+
+  log(
+    enabled
+      ? "[auth] ENABLED — JWT enforced on /mcp + /dev"
+      : "[auth] DISABLED — injecting dev identity (non-production only)",
+  );
+  return enabled ? "enabled" : "disabled";
+}