@unoverse-platform/studio 0.1.90 → 0.1.91

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

@@ -0,0 +1,278 @@
+/**
+ * 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;
+}
+
+/** Validate a bearer token and extract the user, or null if invalid/unconfigured. */
+export async function validateJWT(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";
+}

package/vendor/base/src/boot.ts

@@ -0,0 +1,245 @@
+/**
+ * Boot report — ONE readout at the end of startup, instead of a line per thing loaded.
+ *
+ * Boot used to narrate itself: 84 node ticks, 24 credential ticks, 27 "local wins"
+ * lines, each registration announcing itself as it happened. Two problems with that.
+ * It reads as noise rather than as a product, and a real failure (the plugin-state
+ * fetch that fails silently below) sits in the middle of it styled exactly like a
+ * success tick, so nobody sees it.
+ *
+ * The rule here: COUNT the healthy, NAME the anomalous. A node that loaded is a
+ * number; a node that was skipped, shadowed, disabled or missing metadata is a line
+ * with its name on it. Nothing diagnostic is lost, because the per-item detail is
+ * still emitted at debug level (LOG_LEVEL=debug) and the full catalog is one
+ * `GET /nodes` away.
+ *
+ * Collect from anywhere during boot, print once from index.ts.
+ */
+
+const DEBUG = (process.env.LOG_LEVEL ?? "").toLowerCase() === "debug";
+
+// The readout is a product surface: labels recede, values read, addresses invite the
+// click. One accent, no boxes, and everything still greps clean because whole segments
+// are wrapped rather than words. NO_COLOR is the standard opt-out.
+const COLOR = !process.env.NO_COLOR;
+const paint = (code: string) => (s: string) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = paint("1");
+const dim = paint("2");
+const cyan = paint("36");
+const yellow = paint("33");
+const red = paint("31");
+
+type Notice = { level: "warn" | "error"; text: string };
+type Endpoint = { label: string; url: string; note?: string };
+
+const state = {
+  startedAt: Date.now(),
+  packages: 0,
+  nodes: [] as string[],
+  credentials: [] as string[],
+  credentialsSkipped: 0,
+  components: null as { node: string; count: number } | null,
+  manifests: null as { nodes: number; credentials: number; shadowed: string[]; disabled: string[] } | null,
+  pluginStates: 0,
+  pluginStateError: null as string | null,
+  pluginsLocalWin: [] as string[],
+  pluginsFromNpm: [] as string[],
+  pluginsDisabled: [] as string[],
+  auth: null as string | null,
+  redis: null as string | null,
+  engine: null as string | null,
+  watching: null as string | null,
+  endpoints: [] as Endpoint[],
+  notices: [] as Notice[],
+  printed: false,
+};
+
+/** Per-item detail, kept for LOG_LEVEL=debug. Silent otherwise. */
+function detail(line: string): void {
+  if (DEBUG) console.log(line);
+}
+
+export const boot = {
+  packages(n: number) {
+    state.packages = n;
+    detail(`[boot] discovered ${n} node packages`);
+  },
+
+  node(type: string) {
+    state.nodes.push(type);
+    detail(`[boot]   node ${type}`);
+  },
+
+  credential(name: string, skipped = false) {
+    if (skipped) {
+      // First-wins is the DESIGNED behaviour for a shared credential (several AWS
+      // packages legitimately declare awsCredential), so it is not a warning and
+      // never belonged in the readout. It was 48 warning lines a boot.
+      state.credentialsSkipped++;
+      detail(`[boot]   credential ${name} already registered, kept the first`);
+      return;
+    }
+    state.credentials.push(name);
+    detail(`[boot]   credential ${name}`);
+  },
+
+  components(node: string, count: number) {
+    state.components = { node, count };
+  },
+
+  manifests(m: { nodes: number; credentials: number; shadowed: string[]; disabled: string[] }) {
+    state.manifests = m;
+  },
+
+  pluginStates(n: number) {
+    // Loaded once at boot and again after the engine comes up; the count is the same
+    // fact both times, so the report holds one of it rather than printing twice.
+    state.pluginStates = n;
+  },
+
+  /**
+   * A failed read of the plugin state table. Not a notice on its own: in merged mode the
+   * first read races the engine binding :4101 and is retried. It becomes a notice only
+   * if no state was ever loaded, which is the case where plugins really are missing.
+   */
+  pluginStateFetchFailed(message: string) {
+    state.pluginStateError = message;
+    detail(`[boot]   plugin state read failed: ${message}`);
+  },
+
+  pluginLocalWin(name: string, installedVersion?: string) {
+    state.pluginsLocalWin.push(name);
+    detail(`[boot]   ${name}: local source wins over npm${installedVersion ? ` (npm has ${installedVersion})` : ""}`);
+  },
+
+  pluginFromNpm(name: string, source = "npm") {
+    state.pluginsFromNpm.push(name);
+    detail(`[boot]   ${name}: loaded from ${source}`);
+  },
+
+  pluginDisabled(name: string) {
+    state.pluginsDisabled.push(name);
+  },
+
+  auth(posture: string) {
+    state.auth = posture;
+  },
+
+  redis(status: string) {
+    state.redis = status;
+  },
+
+  engine(where: string) {
+    state.engine = where;
+  },
+
+  /** Manifest hot reload is a dev affordance worth one line, because it changes what a save does. */
+  watching(dir: string) {
+    state.watching = dir;
+  },
+
+  endpoint(label: string, url: string, note?: string) {
+    state.endpoints.push({ label, url, note });
+  },
+
+  /**
+   * Addresses are listed in the order someone reaches for them, not the order the
+   * listeners happened to bind. Studio is what a person opens; the internal runtime is
+   * what a machine calls.
+   */
+  endpointOrder: ["Studio", "MCP", "Runtime", "Builder MCP"],
+
+  notice(level: "warn" | "error", text: string) {
+    state.notices.push({ level, text });
+  },
+
+  /**
+   * True until the report prints. Loaders that run BOTH at boot and later (the manifest
+   * watcher, install/uninstall) ask this: during boot they hand their result to the
+   * report, afterwards they log it themselves, because a reload with nothing else on
+   * screen is a real event and should say so.
+   */
+  isBooting() {
+    return !state.printed;
+  },
+
+  /** Everything the report knows, for a status route or a test. */
+  snapshot() {
+    return { ...state };
+  },
+
+  print() {
+    if (state.printed) return;
+    state.printed = true;
+    const ready = ((Date.now() - state.startedAt) / 1000).toFixed(1);
+
+    const rows: Array<[string, string]> = [];
+    rows.push(["Nodes", `${state.nodes.length} registered from ${state.packages} packages`]);
+    if (state.manifests) {
+      const m = state.manifests;
+      const parts = [`${m.nodes} loaded`];
+      if (m.shadowed.length) parts.push(`${m.shadowed.length} shadowed by code`);
+      if (m.disabled.length) parts.push(`${m.disabled.length} disabled`);
+      rows.push(["Manifests", parts.join(", ")]);
+    }
+    // The skipped count is every re-declaration of a credential that already exists,
+    // which is the shared-credential design working. It is a debug fact, not a headline.
+    rows.push(["Credentials", `${state.credentials.length} types`]);
+    if (state.components) rows.push(["Components", `${state.components.count} in one ${state.components.node} node`]);
+    if (state.pluginStates) {
+      const parts = [`${state.pluginStates} states`];
+      if (state.pluginsLocalWin.length) parts.push(`${state.pluginsLocalWin.length} local over npm`);
+      if (state.pluginsFromNpm.length) parts.push(`${state.pluginsFromNpm.length} from npm`);
+      if (state.pluginsDisabled.length) parts.push(`${state.pluginsDisabled.length} disabled`);
+      rows.push(["Plugins", parts.join(", ")]);
+    }
+    if (state.engine) rows.push(["Engine", state.engine]);
+    if (state.redis) rows.push(["Redis", state.redis]);
+    // Last row before the addresses, because it qualifies every one of them.
+    if (state.auth) rows.push(["Auth", state.auth]);
+    // Trimmed to the repo-relative path: absolute would be the longest string in the
+    // block, and the identifying part is the tail. cwd is not usable for this because
+    // the server is started from several directories (turbo, docker, the CLI).
+    if (state.watching)
+      rows.push(["Watching", `${state.watching.replace(/^.*?(?=apps\/)/, "")}, manifests reload on save`]);
+
+    const labelWidth = Math.max(...rows.map((r) => r[0].length), ...state.endpoints.map((e) => e.label.length));
+    const urlWidth = Math.max(0, ...state.endpoints.map((e) => e.url.length));
+    // Pad BEFORE painting: ANSI codes have width in padEnd's eyes and none on screen.
+    const out: string[] = ["", `  ${bold("unoverse")}    ${dim(`ready in ${ready}s`)}`, ""];
+    for (const [label, value] of rows) out.push(`  ${dim(label.padEnd(labelWidth))}   ${value}`);
+    if (state.endpoints.length) {
+      const rank = (l: string) => {
+        const i = boot.endpointOrder.indexOf(l);
+        return i === -1 ? boot.endpointOrder.length : i;
+      };
+      state.endpoints.sort((a, b) => rank(a.label) - rank(b.label));
+      out.push("");
+      for (const e of state.endpoints) {
+        out.push(`  ${dim(e.label.padEnd(labelWidth))}   ${cyan(e.note ? e.url.padEnd(urlWidth) : e.url)}${e.note ? `   ${dim(e.note)}` : ""}`);
+      }
+    }
+
+    // Anomalies are the point of the readout, so they sit at the bottom where the eye
+    // lands and they are the only thing here that is not a count.
+    if (state.pluginStateError && !state.pluginStates)
+      state.notices.push({
+        level: "error",
+        text: `no plugin state could be read (${state.pluginStateError}), so npm-installed packages did not load`,
+      });
+
+    const anomalies = [
+      ...state.notices.map((n) => `  ${n.level === "error" ? red("✗") : yellow("!")}  ${n.text}`),
+      ...(state.manifests?.shadowed.length
+        ? [`  ${yellow("!")}  code wins over manifest for: ${state.manifests.shadowed.join(", ")}`]
+        : []),
+      ...(state.pluginsDisabled.length
+        ? [`  ${yellow("!")}  disabled, so not loaded: ${state.pluginsDisabled.join(", ")}`]
+        : []),
+    ];
+    if (anomalies.length) out.push("", ...anomalies);
+    out.push("");
+    if (!DEBUG) out.push(dim("  LOG_LEVEL=debug lists every node, credential and package as it loads."), "");
+    console.log(out.join("\n"));
+  },
+};

package/vendor/base/src/definitions/definitions.ts

@@ -0,0 +1,18 @@
+/**
+ * Unoverse definition store — the FAÇADE. Split 2026-08-30 into organised
+ * subfolders (owner: files stay ~500-800 lines, folders group by concern);
+ * every existing import of `definitions/definitions.js` keeps working.
+ *
+ *   registry/homes.ts    where every kind lives; ref → folder resolution
+ *   registry/catalog.ts  listing, app manifests, state order, workbench views
+ *   model.ts             the served shapes + kind/word normalizers
+ *   load/load.ts         loadDefinition — the load core
+ *   load/expand.ts       Ref/atom composition, $include, state inheritance
+ *   load/compile/        the component-tree and template compilers, one file per job
+ */
+export * from "./registry/homes.js";
+export * from "./registry/catalog.js";
+export * from "./model.js";
+export * from "./load/load.js";
+export * from "./load/expand/index.js";
+export * from "./load/compile/index.js";

package/vendor/base/src/definitions/dsPackage.ts

@@ -0,0 +1,45 @@
+/**
+ * The design system as an INSTALLED PACKAGE, wherever the HOST put it.
+ *
+ * Every other tier in `definitions.ts` and `theme.ts` is a path under the content home,
+ * which is the developer's own project. That is right for a universe, where the design
+ * system is installed INTO the deployment, and wrong for Studio, which is a TOOL run
+ * against somebody else's folder. Studio depends on `@unoverse-platform/marketplace`, so
+ * it already carries the design system in its own node_modules, and then went looking for
+ * it in a project that will never have one.
+ *
+ * A new Studio project therefore had NO design system at all: zero components, zero atoms,
+ * no foundation styles (measured against an empty home: 17 components and 30 atoms resolve
+ * with this, none without). Primitives still render, so the scaffolded Welcome component
+ * looks fine and hides it; the failure surfaces later, on the first `Card` or token. And it
+ * is silent either way, because both callers fall through to a path rather than raising.
+ *
+ * ASKED OF NODE rather than walked, so it is found from wherever the host is installed.
+ * NOT a dependency: `marketplace` depends on THIS package, so declaring it would be a
+ * cycle. Absent is a normal answer (a universe resolves from a tier above), hence the
+ * catch, and the answer is memoized because a failed resolve is the expensive case.
+ *
+ * ITS OWN MODULE so `definitions.ts` and `theme.ts` share one implementation without
+ * importing each other. They resolve different kinds out of the same bundle
+ * (components/atoms, and styles), and two copies of this would drift into two answers
+ * about where the design system is.
+ *
+ * SEARCHED LAST by both callers, after every project-local tier, so nothing changes for a
+ * host that already resolves: this fires only where the alternative was nothing at all.
+ */
+import { join, dirname } from "path";
+import { createRequire } from "module";
+
+let cached: string | null | undefined;
+
+/** The bundle's `definitions/` folder, or null when the package is not installed. */
+export function packagedDesignSystem(): string | null {
+  if (cached !== undefined) return cached;
+  try {
+    const pkg = createRequire(import.meta.url).resolve("@unoverse-platform/marketplace/package.json");
+    cached = join(dirname(pkg), "definitions");
+  } catch {
+    cached = null;
+  }
+  return cached;
+}