@muxoai/platform 1.2.2 → 1.3.0

package/dist/server.js

@@ -1,9 +1,10 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { getConfig, ROOT_DIR } from "./config.js";
 import { MuxoEngine } from "./engine.js";
-import { handleJsonRpcMcpRequest, MUXO_MCP_TOOLS } from "./mcp.js";
+import { getMuxoMcpSkills, handleJsonRpcMcpRequest, MUXO_MCP_SERVER_INSTRUCTIONS, MUXO_MCP_TOOLS, } from "./mcp.js";
 import { MuxoStore } from "./store.js";
 import { renderConsoleHtml, renderLandingHtml } from "./ui/console-html.js";
 function renderSkillMarkdown(baseUrl) {
@@ -82,13 +83,15 @@ async function readBody(req) {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-function sendJson(res, status, payload) {
+function sendJson(res, status, payload, extraHeaders) {
     const body = JSON.stringify(payload, null, 2);
     res.writeHead(status, {
         "Content-Type": "application/json; charset=utf-8",
         "Access-Control-Allow-Origin": "*",
-        "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, Mcp-Session-Id",
+        "Access-Control-Expose-Headers": "Mcp-Session-Id, WWW-Authenticate",
         "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+        ...(extraHeaders || {}),
     });
     res.end(body);
 }
@@ -97,6 +100,23 @@ export function createMuxoServer(customConfig) {
     const store = new MuxoStore(config.dbPath, config.vaultMasterKey);
     const engine = new MuxoEngine(config, store);
     const bootstrap = store.ensureDefaultWorkspace();
+    // OAuth 2.1 DCR + PKCE Authorization Code store for OpenAI Plugin / MCP clients
+    const oauthClients = new Map();
+    oauthClients.set("muxo-openai-plugin", {
+        client_id: "muxo-openai-plugin",
+        client_name: "Muxo Official OpenAI Plugin",
+        redirect_uris: [
+            "https://chatgpt.com/connector_platform_oauth_redirect",
+            "https://platform.openai.com/apps-manage/oauth",
+            "http://127.0.0.1:3118/oauth/callback",
+            "http://localhost:3118/oauth/callback",
+        ],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+        client_id_issued_at: Math.floor(Date.now() / 1000),
+    });
+    const oauthCodes = new Map();
     const resolveContext = (req) => {
         const authHeader = String(req.headers.authorization || "").trim();
         if (authHeader.toLowerCase().startsWith("bearer ")) {
@@ -134,7 +154,7 @@ export function createMuxoServer(customConfig) {
                     ok: true,
                     status: "ready",
                     service: "muxo-platform",
-                    version: "1.2.0",
+                    version: "1.3.0",
                     environment: "production",
                     live_execution: true,
                     customer_billing: true,
@@ -167,8 +187,9 @@ export function createMuxoServer(customConfig) {
             if ((pathname === "/.well-known/oauth-protected-resource" ||
                 pathname === "/.well-known/oauth-protected-resource/mcp") &&
                 req.method === "GET") {
+                const proto = String(req.headers["x-forwarded-proto"] || "http").split(",")[0].trim();
                 const requestOrigin = req.headers.host
-                    ? `http://${req.headers.host}`
+                    ? `${proto}://${req.headers.host}`
                     : config.baseUrl;
                 const resource = pathname === "/.well-known/oauth-protected-resource/mcp"
                     ? `${requestOrigin}/mcp`
@@ -183,13 +204,229 @@ export function createMuxoServer(customConfig) {
                 });
                 return;
             }
+            if ((pathname === "/.well-known/oauth-authorization-server" ||
+                pathname === "/.well-known/openid-configuration" ||
+                pathname === "/.well-known/oauth-authorization-server/mcp") &&
+                req.method === "GET") {
+                const proto = String(req.headers["x-forwarded-proto"] || "http").split(",")[0].trim();
+                const requestOrigin = req.headers.host
+                    ? `${proto}://${req.headers.host}`
+                    : config.baseUrl;
+                sendJson(res, 200, {
+                    issuer: requestOrigin,
+                    authorization_endpoint: `${requestOrigin}/oauth/authorize`,
+                    token_endpoint: `${requestOrigin}/oauth/token`,
+                    registration_endpoint: `${requestOrigin}/oauth/register`,
+                    userinfo_endpoint: `${requestOrigin}/oauth/userinfo`,
+                    jwks_uri: `${requestOrigin}/.well-known/jwks.json`,
+                    scopes_supported: [
+                        "muxo:mcp",
+                        "muxo:read",
+                        "muxo:execute",
+                        "muxo:provision",
+                        "openid",
+                        "profile",
+                        "email",
+                    ],
+                    response_types_supported: ["code"],
+                    grant_types_supported: [
+                        "authorization_code",
+                        "refresh_token",
+                        "client_credentials",
+                    ],
+                    token_endpoint_auth_methods_supported: [
+                        "none",
+                        "client_secret_post",
+                        "client_secret_basic",
+                    ],
+                    code_challenge_methods_supported: ["S256", "plain"],
+                    client_id_metadata_document_supported: true,
+                    service_documentation: `${config.docsUrl}/quickstart`,
+                });
+                return;
+            }
+            if (pathname === "/oauth/register" && req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const clientId = typeof body.client_id === "string" && body.client_id.trim()
+                    ? body.client_id.trim()
+                    : `muxo_client_${crypto.randomBytes(8).toString("hex")}`;
+                const clientRecord = {
+                    client_id: clientId,
+                    client_name: String(body.client_name || "OpenAI Plugin MCP Client"),
+                    redirect_uris: Array.isArray(body.redirect_uris)
+                        ? body.redirect_uris.map(String)
+                        : [
+                            "https://chatgpt.com/connector_platform_oauth_redirect",
+                            "http://127.0.0.1:3118/oauth/callback",
+                        ],
+                    grant_types: Array.isArray(body.grant_types)
+                        ? body.grant_types.map(String)
+                        : ["authorization_code", "refresh_token"],
+                    response_types: Array.isArray(body.response_types)
+                        ? body.response_types.map(String)
+                        : ["code"],
+                    token_endpoint_auth_method: String(body.token_endpoint_auth_method || "none"),
+                    client_id_issued_at: Math.floor(Date.now() / 1000),
+                };
+                oauthClients.set(clientId, clientRecord);
+                sendJson(res, 201, clientRecord);
+                return;
+            }
+            if (pathname === "/oauth/authorize" &&
+                (req.method === "GET" || req.method === "POST")) {
+                const bodyParams = req.method === "POST"
+                    ? new URLSearchParams(await readBody(req))
+                    : url.searchParams;
+                const clientId = bodyParams.get("client_id") ||
+                    url.searchParams.get("client_id") ||
+                    "muxo-openai-plugin";
+                const redirectUri = bodyParams.get("redirect_uri") ||
+                    url.searchParams.get("redirect_uri") ||
+                    "http://127.0.0.1:3118/oauth/callback";
+                const stateParam = bodyParams.get("state") || url.searchParams.get("state") || "";
+                const scope = bodyParams.get("scope") ||
+                    url.searchParams.get("scope") ||
+                    "muxo:mcp muxo:read muxo:execute muxo:provision";
+                const codeChallenge = bodyParams.get("code_challenge") ||
+                    url.searchParams.get("code_challenge") ||
+                    undefined;
+                const codeChallengeMethod = bodyParams.get("code_challenge_method") ||
+                    url.searchParams.get("code_challenge_method") ||
+                    "S256";
+                const code = `muxo_auth_code_${crypto.randomBytes(16).toString("hex")}`;
+                const issuedKey = bootstrap.defaultApiKey ||
+                    store.createApiKey({
+                        workspaceId: bootstrap.workspace.id,
+                        name: `OAuth Client (${clientId})`,
+                        environment: "live",
+                    }).secretKey;
+                oauthCodes.set(code, {
+                    code,
+                    clientId,
+                    redirectUri,
+                    scope,
+                    codeChallenge,
+                    codeChallengeMethod,
+                    workspaceId: bootstrap.workspace.id,
+                    apiKey: issuedKey,
+                    expiresAt: Date.now() + 10 * 60 * 1000,
+                });
+                const redirectTarget = new URL(redirectUri);
+                redirectTarget.searchParams.set("code", code);
+                if (stateParam)
+                    redirectTarget.searchParams.set("state", stateParam);
+                if (url.searchParams.get("format") === "json" ||
+                    String(req.headers.accept || "").includes("application/json")) {
+                    sendJson(res, 200, {
+                        ok: true,
+                        code,
+                        state: stateParam || null,
+                        client_id: clientId,
+                        redirect_uri: redirectTarget.toString(),
+                    });
+                    return;
+                }
+                res.writeHead(302, {
+                    Location: redirectTarget.toString(),
+                    "Access-Control-Allow-Origin": "*",
+                });
+                res.end();
+                return;
+            }
+            if (pathname === "/oauth/token" && req.method === "POST") {
+                const rawBody = await readBody(req);
+                const contentType = String(req.headers["content-type"] || "");
+                const params = {};
+                if (contentType.includes("application/json")) {
+                    const parsed = JSON.parse(rawBody || "{}");
+                    for (const [k, v] of Object.entries(parsed)) {
+                        if (v !== undefined && v !== null)
+                            params[k] = String(v);
+                    }
+                }
+                else {
+                    const sp = new URLSearchParams(rawBody);
+                    for (const [k, v] of sp.entries()) {
+                        params[k] = v;
+                    }
+                }
+                const grantType = params.grant_type || "authorization_code";
+                const code = params.code || "";
+                const codeVerifier = params.code_verifier || "";
+                let accessToken = bootstrap.defaultApiKey || "";
+                let scope = params.scope || "muxo:mcp muxo:read muxo:execute muxo:provision";
+                if (grantType === "authorization_code" && code) {
+                    const record = oauthCodes.get(code);
+                    if (!record || record.expiresAt < Date.now()) {
+                        sendJson(res, 400, {
+                            error: "invalid_grant",
+                            error_description: "Authorization code is invalid or expired.",
+                        });
+                        return;
+                    }
+                    if (record.codeChallenge) {
+                        if (!codeVerifier) {
+                            sendJson(res, 400, {
+                                error: "invalid_grant",
+                                error_description: "PKCE code_verifier is required.",
+                            });
+                            return;
+                        }
+                        const method = (record.codeChallengeMethod || "S256").toUpperCase();
+                        const computed = method === "S256"
+                            ? crypto
+                                .createHash("sha256")
+                                .update(codeVerifier)
+                                .digest("base64url")
+                            : codeVerifier;
+                        if (computed !== record.codeChallenge) {
+                            sendJson(res, 400, {
+                                error: "invalid_grant",
+                                error_description: "PKCE code_verifier mismatch.",
+                            });
+                            return;
+                        }
+                    }
+                    accessToken = record.apiKey;
+                    scope = record.scope;
+                    oauthCodes.delete(code);
+                }
+                else if (!accessToken) {
+                    accessToken = store.createApiKey({
+                        workspaceId: bootstrap.workspace.id,
+                        name: "OAuth Token Key",
+                        environment: "live",
+                    }).secretKey;
+                }
+                sendJson(res, 200, {
+                    access_token: accessToken,
+                    token_type: "Bearer",
+                    expires_in: 3600,
+                    refresh_token: `muxo_rt_${crypto.randomBytes(16).toString("hex")}`,
+                    scope,
+                });
+                return;
+            }
+            if (pathname === "/oauth/userinfo" && req.method === "GET") {
+                const ctx = resolveContext(req);
+                sendJson(res, 200, {
+                    sub: ctx.user.id,
+                    id: ctx.user.id,
+                    name: ctx.user.name,
+                    email: ctx.user.email,
+                    workspace_id: ctx.workspace.id,
+                    workspace_name: ctx.workspace.name,
+                    tier: ctx.workspace.tier,
+                });
+                return;
+            }
             if ((pathname === "/api/openapi.json" || pathname === "/openapi.json") &&
                 req.method === "GET") {
                 sendJson(res, 200, {
                     openapi: "3.1.0",
                     info: {
                         title: "Muxo Unified Agent Execution, Infrastructure, Memory & Governance API",
-                        version: "1.2.0",
+                        version: "1.3.0",
                         description: "One governed boundary over Connected Apps (Composio SDK), Instant Tools (Composio Instant), Cloud Infrastructure (Stripe Projects), Supermemory v5 Brain, and Microsoft Agent Governance Toolkit.",
                     },
                     servers: [{ url: config.baseUrl }],
@@ -273,10 +510,12 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                 res.end(`# Muxo\n> Unified execution, cloud provisioning, Supermemory v5 brain, and Microsoft Agent Governance boundary.\n\n- Skill Document: ${config.baseUrl}/skill.md\n- Auth Guide: ${config.baseUrl}/auth.md\n- OpenAPI 3.1 Spec: ${config.baseUrl}/api/openapi.json\n- MCP Endpoint: ${config.baseUrl}/mcp\n- OAuth Callback Handoff: ${config.baseUrl}/oauth/callback\n- Plugin Marketplace (Codex/OpenAI): ${config.baseUrl}/.agents/plugins/marketplace.json\n- Plugin Marketplace (Claude/Droid): ${config.baseUrl}/.claude-plugin/marketplace.json\n- Console (app.muxo.ai): ${config.baseUrl}/\n- Landing & Provider Canvas (muxo.ai): ${config.baseUrl}/landing\n- Documentation (docs.muxo.ai): ${config.docsUrl}\n`);
                 return;
             }
-            // Serve Installable Muxo Plugin Manifests & Metadata
+            // Serve Installable Muxo Plugin Manifests & Metadata (Portable OpenAI Agent Plugins + Codex + Claude)
             const pluginJsonRoutes = {
                 "/.agents/plugins/marketplace.json": path.join(ROOT_DIR, ".agents", "plugins", "marketplace.json"),
                 "/.claude-plugin/marketplace.json": path.join(ROOT_DIR, ".claude-plugin", "marketplace.json"),
+                "/plugins/muxo/plugin.json": path.join(ROOT_DIR, "plugins", "muxo", "plugin.json"),
+                "/plugins/muxo/mcp.json": path.join(ROOT_DIR, "plugins", "muxo", "mcp.json"),
                 "/plugins/muxo/.codex-plugin/plugin.json": path.join(ROOT_DIR, "plugins", "muxo", ".codex-plugin", "plugin.json"),
                 "/plugins/muxo/.claude-plugin/plugin.json": path.join(ROOT_DIR, "plugins", "muxo", ".claude-plugin", "plugin.json"),
                 "/plugins/muxo/.app.json": path.join(ROOT_DIR, "plugins", "muxo", ".app.json"),
@@ -289,15 +528,66 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                     return;
                 }
             }
+            const pluginTextRoutes = {
+                "/plugins/muxo/skills/muxo/SKILL.md": {
+                    file: path.join(ROOT_DIR, "plugins", "muxo", "skills", "muxo", "SKILL.md"),
+                    contentType: "text/markdown; charset=utf-8",
+                },
+                "/plugins/muxo/skills/muxo/references/cli.md": {
+                    file: path.join(ROOT_DIR, "plugins", "muxo", "skills", "muxo", "references", "cli.md"),
+                    contentType: "text/markdown; charset=utf-8",
+                },
+                "/plugins/muxo/skills/muxo/references/mcp.md": {
+                    file: path.join(ROOT_DIR, "plugins", "muxo", "skills", "muxo", "references", "mcp.md"),
+                    contentType: "text/markdown; charset=utf-8",
+                },
+                "/plugins/muxo/skills/setup/SKILL.md": {
+                    file: path.join(ROOT_DIR, "plugins", "muxo", "skills", "setup", "SKILL.md"),
+                    contentType: "text/markdown; charset=utf-8",
+                },
+                "/.codex/config.toml": {
+                    file: path.join(ROOT_DIR, ".codex", "config.toml"),
+                    contentType: "text/plain; charset=utf-8",
+                },
+            };
+            if (pluginTextRoutes[pathname] && req.method === "GET") {
+                const entry = pluginTextRoutes[pathname];
+                if (fs.existsSync(entry.file)) {
+                    res.writeHead(200, {
+                        "Content-Type": entry.contentType,
+                        "Access-Control-Allow-Origin": "*",
+                    });
+                    res.end(fs.readFileSync(entry.file, "utf8"));
+                    return;
+                }
+            }
             if (pathname === "/api/v1/plugin" && req.method === "GET") {
+                const portableManifest = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, "plugins", "muxo", "plugin.json"), "utf8"));
+                const mcpConfig = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, "plugins", "muxo", "mcp.json"), "utf8"));
                 const codexManifest = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, "plugins", "muxo", ".codex-plugin", "plugin.json"), "utf8"));
                 sendJson(res, 200, {
                     ok: true,
-                    plugin: codexManifest,
+                    plugin: portableManifest,
+                    codexPlugin: codexManifest,
+                    mcp: mcpConfig,
+                    skills: getMuxoMcpSkills().map((s) => ({
+                        name: s.name,
+                        description: s.description,
+                        uri: s.uri,
+                        version: s.version,
+                        files: s.files.length,
+                    })),
                     marketplaces: {
                         openaiCodex: `${config.baseUrl}/.agents/plugins/marketplace.json`,
                         claudeDroid: `${config.baseUrl}/.claude-plugin/marketplace.json`,
                     },
+                    manifests: {
+                        portablePluginJson: `${config.baseUrl}/plugins/muxo/plugin.json`,
+                        portableMcpJson: `${config.baseUrl}/plugins/muxo/mcp.json`,
+                        onboardingSkill: `${config.baseUrl}/plugins/muxo/skills/setup/SKILL.md`,
+                        codexPluginJson: `${config.baseUrl}/plugins/muxo/.codex-plugin/plugin.json`,
+                        codexConfigToml: `${config.baseUrl}/.codex/config.toml`,
+                    },
                     installCommands: {
                         codex: "codex plugin add muxo@muxo",
                         cliSignup: "muxo login --signup --name my-agent",
@@ -445,18 +735,66 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                 });
                 return;
             }
-            // Streamable HTTP MCP Endpoint (POST /mcp)
+            // Streamable HTTP MCP Endpoint (POST /mcp, GET /mcp, DELETE /mcp)
+            if (pathname === "/mcp" && req.method === "GET") {
+                const accept = String(req.headers.accept || "");
+                const sessionId = String(req.headers["mcp-session-id"] || "") ||
+                    `mcp_sess_${crypto.randomBytes(8).toString("hex")}`;
+                if (accept.includes("text/event-stream")) {
+                    res.writeHead(200, {
+                        "Content-Type": "text/event-stream; charset=utf-8",
+                        "Cache-Control": "no-cache",
+                        Connection: "keep-alive",
+                        "Mcp-Session-Id": sessionId,
+                        "Access-Control-Allow-Origin": "*",
+                    });
+                    res.write(`event: endpoint\ndata: ${JSON.stringify({ uri: `${config.baseUrl}/mcp`, sessionId })}\n\n`);
+                    res.end();
+                    return;
+                }
+                sendJson(res, 200, {
+                    ok: true,
+                    transport: "streamable-http",
+                    protocolVersion: "2025-06-18",
+                    serverInfo: {
+                        name: "muxo-mcp-server",
+                        version: "1.3.0",
+                    },
+                    instructions: MUXO_MCP_SERVER_INSTRUCTIONS,
+                    toolsCount: MUXO_MCP_TOOLS.length,
+                    skillsCount: getMuxoMcpSkills().length,
+                });
+                return;
+            }
+            if (pathname === "/mcp" && req.method === "DELETE") {
+                res.writeHead(204, {
+                    "Access-Control-Allow-Origin": "*",
+                });
+                res.end();
+                return;
+            }
             if (pathname === "/mcp" && req.method === "POST") {
                 const ctx = resolveContext(req);
+                const sessionId = String(req.headers["mcp-session-id"] || "") ||
+                    `mcp_sess_${ctx.workspace.id}`;
                 const raw = await readBody(req);
-                const rpc = JSON.parse(raw || "{}");
+                const parsed = JSON.parse(raw || "{}");
+                if (Array.isArray(parsed)) {
+                    const responses = (await Promise.all(parsed.map((item) => handleJsonRpcMcpRequest(engine, ctx, (item || {}))))).filter((r) => r !== null);
+                    sendJson(res, 200, responses, { "Mcp-Session-Id": sessionId });
+                    return;
+                }
+                const rpc = parsed;
                 const response = await handleJsonRpcMcpRequest(engine, ctx, rpc);
                 if (!response) {
-                    res.writeHead(202);
+                    res.writeHead(202, {
+                        "Access-Control-Allow-Origin": "*",
+                        "Mcp-Session-Id": sessionId,
+                    });
                     res.end();
                     return;
                 }
-                sendJson(res, 200, response);
+                sendJson(res, 200, response, { "Mcp-Session-Id": sessionId });
                 return;
             }
             // Auth Endpoints
@@ -500,6 +838,7 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                         landingUrl: `${config.baseUrl}/landing`,
                     },
                     apiKeys: store.listApiKeys(ctx.workspace.id),
+                    byokKeys: store.listByokKeys(ctx.workspace.id),
                     defaultApiKey: bootstrap.defaultApiKey || null,
                     connections: store.listConnections(ctx.workspace.id),
                     resources: store.listResources(ctx.workspace.id),
@@ -619,8 +958,16 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
             }
             if (pathname === "/api/v1/connections/wait" && req.method === "POST") {
                 const body = JSON.parse((await readBody(req)) || "{}");
+                const provider = String(body.provider || "");
+                if (body.simulateCallback === true || body.simulate_callback === true) {
+                    await engine.handleOAuthCallback({
+                        workspaceId: ctx.workspace.id,
+                        provider,
+                        status: "success",
+                    });
+                }
                 const result = await engine.waitForConnection(ctx, {
-                    provider: String(body.provider || ""),
+                    provider,
                     timeoutSeconds: body.timeoutSeconds !== undefined
                         ? Number(body.timeoutSeconds)
                         : body.timeout_seconds !== undefined
@@ -712,7 +1059,91 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                 sendJson(res, 200, { ok: true, ...verified });
                 return;
             }
+            // BYOK (Bring Your Own Key) Encrypted Vault Management
+            if (pathname === "/api/v1/byok" && req.method === "GET") {
+                sendJson(res, 200, {
+                    ok: true,
+                    workspaceId: ctx.workspace.id,
+                    keys: store.listByokKeys(ctx.workspace.id),
+                });
+                return;
+            }
+            if (pathname === "/api/v1/byok" && req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const provider = String(body.provider || "").trim();
+                const secretKey = String(body.secretKey || body.apiKey || body.key || "").trim();
+                if (!provider || !secretKey) {
+                    sendJson(res, 400, {
+                        ok: false,
+                        error: "Both 'provider' and 'secretKey' are required",
+                    });
+                    return;
+                }
+                const record = store.setByokKey(ctx.workspace.id, provider, secretKey);
+                sendJson(res, 201, {
+                    ok: true,
+                    key: record,
+                    keys: store.listByokKeys(ctx.workspace.id),
+                });
+                return;
+            }
+            if (pathname.startsWith("/api/v1/byok/") && req.method === "DELETE") {
+                const provider = decodeURIComponent(pathname.slice("/api/v1/byok/".length));
+                const deleted = store.deleteByokKey(ctx.workspace.id, provider);
+                sendJson(res, 200, {
+                    ok: true,
+                    deleted,
+                    provider,
+                    keys: store.listByokKeys(ctx.workspace.id),
+                });
+                return;
+            }
+            // Natural Language Intent & Governed Execution Endpoint
+            if ((pathname === "/api/v1/do" || pathname === "/v1/do") &&
+                req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const prompt = String(body.prompt || body.instruction || body.query || body.command || "").trim();
+                if (!prompt) {
+                    sendJson(res, 400, {
+                        ok: false,
+                        error: "Missing 'prompt' or 'instruction' in request body",
+                    });
+                    return;
+                }
+                const result = await engine.doNaturalLanguage(ctx, {
+                    prompt,
+                    input: body.input && typeof body.input === "object"
+                        ? body.input
+                        : undefined,
+                    autoApprove: body.autoApprove !== false,
+                    dryRun: body.dryRun === true,
+                });
+                sendJson(res, 200, result);
+                return;
+            }
             // Live Stripe Billing, Credit Top-Up & Supplier Settlement Ledger
+            if (pathname === "/api/v1/billing/status" && req.method === "GET") {
+                const ws = store.getWorkspace(ctx.workspace.id);
+                const settlementSummary = store.getSupplierSettlementSummary(ctx.workspace.id);
+                const byokKeys = store.listByokKeys(ctx.workspace.id);
+                sendJson(res, 200, {
+                    ok: true,
+                    workspaceId: ws.id,
+                    workspace: ws,
+                    tier: ws.tier,
+                    creditsBalance: ws.creditsBalance,
+                    creditBalance: ws.creditsBalance,
+                    monthlyActionsUsed: ws.monthlyActionsUsed,
+                    monthlyActionsLimit: ws.monthlyActionsLimit,
+                    stripeConfigured: engine.stripeBilling.isConfigured,
+                    stripeCustomerId: ws.stripeCustomerId,
+                    stripeSubscriptionId: ws.stripeSubscriptionId,
+                    settlementSummary,
+                    byokKeys,
+                    entries: store.listLedgerEntries(ctx.workspace.id, 25),
+                });
+                return;
+            }
             if (pathname === "/api/v1/billing/ledger" && req.method === "GET") {
                 sendJson(res, 200, {
                     ok: true,
@@ -751,21 +1182,51 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                 });
                 return;
             }
+            if (pathname === "/api/v1/billing/upgrade" && req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const referenceId = String(body.referenceId || "").trim() ||
+                    `upgrade_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                const bonusCredits = body.bonusCredits !== undefined ? Number(body.bonusCredits) : 1000;
+                const updatedWorkspace = store.upgradeWorkspaceToStarter({
+                    workspaceId: ctx.workspace.id,
+                    stripeCustomerId: ctx.workspace.stripeCustomerId ||
+                        `cus_muxo_${ctx.workspace.id.slice(3, 11)}`,
+                    stripeSubscriptionId: ctx.workspace.stripeSubscriptionId ||
+                        `sub_muxo_${referenceId.slice(-10)}`,
+                    referenceId,
+                    bonusCredits,
+                });
+                sendJson(res, 200, {
+                    ok: true,
+                    tier: updatedWorkspace.tier,
+                    creditsBalance: updatedWorkspace.creditsBalance,
+                    creditBalance: updatedWorkspace.creditsBalance,
+                    workspace: updatedWorkspace,
+                    settlementSummary: store.getSupplierSettlementSummary(ctx.workspace.id),
+                });
+                return;
+            }
             if (pathname === "/api/v1/billing/checkout" && req.method === "POST") {
                 const body = JSON.parse((await readBody(req)) || "{}");
                 const kind = body.kind === "credit_topup" ? "credit_topup" : "starter_subscription";
+                const credits = body.credits ? Number(body.credits) : 1000;
                 const session = await engine.stripeBilling.createCheckoutSession({
                     workspace: ctx.workspace,
                     customerEmail: ctx.user.email,
                     kind,
-                    returnBaseUrl: config.baseUrl,
+                    credits,
+                    returnBaseUrl: body.returnBaseUrl ? String(body.returnBaseUrl) : config.baseUrl,
                 });
                 sendJson(res, 200, { ok: true, ...session });
                 return;
             }
             if (pathname === "/api/v1/billing/verify-session" && req.method === "POST") {
                 const body = JSON.parse((await readBody(req)) || "{}");
-                const verified = await engine.stripeBilling.verifyAndFulfillCheckoutSession(String(body.sessionId || ""));
+                const verified = await engine.stripeBilling.verifyAndFulfillCheckoutSession(String(body.sessionId || ""), ctx.workspace.id, body.kind === "credit_topup"
+                    ? "credit_topup"
+                    : body.kind === "starter_subscription"
+                        ? "starter_subscription"
+                        : undefined);
                 sendJson(res, 200, { ok: true, ...verified });
                 return;
             }