Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
"use client";
import { createContext, useContext, useEffect, useState } from "react";
import { parseBaseUrl } from "./base-url-parse";
import {
APP_PARAM,
DEFAULT_API_BASE,
DEFAULT_APP_ORIGIN,
DEFAULT_MCP_ENDPOINT,
HOST_PARAM,
HOST_PLACEHOLDER,
} from "./config-constants";
export { DEFAULT_API_BASE, DEFAULT_MCP_ENDPOINT, HOST_PLACEHOLDER };
const BASE_STORAGE_KEY = "carbon-api-base";
const APP_STORAGE_KEY = "carbon-app-origin";
const KEY_STORAGE_KEY = "carbon-api-key";
const API_KEY_PLACEHOLDER = "<api-key>";
/** A host that arrived in the URL rather than from the reader is only trusted to
* DISPLAY. Pasting the reader's stored key into samples aimed at it would hand a
* crafted link their credential, so the key is withheld until they confirm the
* instance in the dialog. Cleartext http is refused outright (except loopback,
* which never leaves the machine) — a key in a copy-pasted http:// sample is a
* key on the wire. */
function isTrustedForCredentials(base: string | null): boolean {
if (base === null) return false;
try {
const u = new URL(base);
if (u.protocol === "https:") return true;
return u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
} catch {
return false;
}
}
type Ctx = {
/** null = the reader's instance is unknown; render HOST_PLACEHOLDER instead. */
base: string | null;
setBase: (v: string | null, app?: string | null) => void;
/** App host (Settings, MCP, and every `/api/v1` sample). Configured separately
* from the REST host upstream, so it is carried explicitly rather than guessed
* from `base` — and settable on its own, since the Carbon API surface picks a
* region while the Data API surface picks a REST host. */
appBase: string | null;
setAppBase: (v: string | null) => void;
isDefault: boolean;
isUnknown: boolean;
apiKey: string;
setApiKey: (v: string) => void;
/** Ask the nearest in-provider Configurator to open (from a placeholder click). */
openConfigurator: () => void;
/** Bumped by openConfigurator. Each Configurator keeps its OWN open state and
* watches this instead of sharing one — the mobile drawer and the sidebar both
* mount a Configurator at once, and a shared boolean would open both dialogs. */
openRequest: number;
};
const ApiConfigCtx = createContext<Ctx>({
base: null,
setBase: () => {},
appBase: null,
setAppBase: () => {},
isDefault: false,
isUnknown: true,
apiKey: "",
setApiKey: () => {},
openConfigurator: () => {},
openRequest: 0,
});
export function ApiConfigProvider({ children }: { children: React.ReactNode }) {
// Unknown until proven otherwise — showing rest.carbon.ms to a self-hosted
// reader is the bug this state exists to fix.
const [base, setBaseState] = useState<string | null>(null);
const [appBase, setAppBaseState] = useState<string | null>(null);
const [apiKey, setApiKeyState] = useState("");
// Where `base` came from. Trust is derived from this + the scheme below, rather
// than stored, so no writer can forget to keep a parallel flag in sync.
const [baseFromLink, setBaseFromLink] = useState(false);
const [openRequest, setOpenRequest] = useState(0);
useEffect(() => {
try {
// Precedence: a choice the reader saved themselves outranks the `?host=`
// hint from a referring app, which outranks "unknown".
const savedBase = localStorage.getItem(BASE_STORAGE_KEY);
const savedApp = localStorage.getItem(APP_STORAGE_KEY);
const savedKey = localStorage.getItem(KEY_STORAGE_KEY);
if (savedKey) setApiKeyState(savedKey);
// Read on its own: the Carbon API surface saves a region (app origin) without
// ever touching the REST base, so gating this on `savedBase` dropped that
// choice on every reload.
if (savedApp) setAppBaseState(savedApp);
if (savedBase) {
// Saved by the reader in the dialog, so the key may be shown against it.
setBaseState(savedBase);
return;
}
// Both params are read independently: the ERP emits each only when its own
// env var is set, and `CARBON_API_URL` is optional while the app origin
// always resolves — so an `?app=`-only link is the ordinary shape for a
// deployment that never configured a REST origin.
const params = new URLSearchParams(window.location.search);
// Display-only: NOT persisted and never credential-trusted. Persisting would
// make one crafted link permanently redirect this reader's samples, and the
// dialog is where a host becomes the reader's own choice.
const hostParam = params.get(HOST_PARAM);
if (hostParam) {
const result = parseBaseUrl(hostParam);
if ("url" in result) {
setBaseState(result.url);
setBaseFromLink(true);
}
}
const appParam = params.get(APP_PARAM);
if (appParam) {
const appResult = parseBaseUrl(appParam);
if ("url" in appResult) setAppBaseState(appResult.url);
}
} catch {}
}, []);
/** The Carbon API surface's own setter: `/api/v1` samples, the MCP endpoint and
* the Settings links all hang off the app origin, and none of them care which
* REST host the Data API surface is pointed at. */
const setAppBase = (v: string | null) => {
const val = v === null ? null : v.trim().replace(/\/+$/, "");
setAppBaseState(val || null);
try {
if (val) localStorage.setItem(APP_STORAGE_KEY, val);
else localStorage.removeItem(APP_STORAGE_KEY);
} catch {}
};
/** Saving through the dialog is what makes a host the reader's OWN choice, so this
* is the only path that persists one or lets the key be shown against it.
* `app` is the instance's app host when known (the ERP passes it; the two are
* configured independently upstream), else null to fall back to the rest.->app. guess. */
const setBase = (v: string | null, app: string | null = null) => {
if (v === null) {
setBaseState(null);
setBaseFromLink(false);
try {
localStorage.removeItem(BASE_STORAGE_KEY);
} catch {}
return;
}
const val = (v || "").trim().replace(/\/+$/, "");
if (!val) return;
setBaseState(val);
setBaseFromLink(false);
try {
localStorage.setItem(BASE_STORAGE_KEY, val);
} catch {}
if (app) setAppBase(app);
};
const setApiKey = (v: string) => {
const val = (v || "").trim();
setApiKeyState(val);
try {
if (val) localStorage.setItem(KEY_STORAGE_KEY, val);
else localStorage.removeItem(KEY_STORAGE_KEY);
} catch {}
};
return (
<ApiConfigCtx.Provider
value={{
base,
setBase,
appBase,
setAppBase,
isDefault: base === DEFAULT_API_BASE,
isUnknown: base === null,
// Withheld while the host came from a link rather than the reader, and for
// any cleartext destination — samples would otherwise carry a real key there.
apiKey: baseFromLink || !isTrustedForCredentials(base) ? "" : apiKey,
setApiKey,
openConfigurator: () => setOpenRequest((n) => n + 1),
openRequest,
}}
>
{children}
</ApiConfigCtx.Provider>
);
}
export const useApiConfig = () => useContext(ApiConfigCtx);
/** Rewrite the default base URL in a sample to the configured instance, or to the
* `<your-host>` placeholder when the instance is unknown. */
export function applyBase(text: string, base: string | null): string {
if (!text) return text;
const replacement = base ?? HOST_PLACEHOLDER;
if (replacement === DEFAULT_API_BASE) return text;
return text.split(DEFAULT_API_BASE).join(replacement);
}
/** App base for the configured instance (where Settings and the MCP server live).
* Returns null when the instance is unknown, so callers render the placeholder.
*
* `appBase` wins whenever it is known: upstream the app host and the REST host are
* separate settings (`ERP_URL` vs `CARBON_API_URL`) and need not share a domain, so
* the `rest.` -> `app.` rewrite below is only a fallback for a host the reader typed
* themselves. Either way any path prefix survives, because `parseBaseUrl` preserves
* one: an instance under `https://acme.com/api/v1` must not lose that segment here
* while the REST samples keep it. */
export function appOrigin(base: string | null, appBase: string | null = null): string | null {
if (appBase) return appBase.replace(/\/+$/, "");
if (base === null) return null;
if (base === DEFAULT_API_BASE) return DEFAULT_APP_ORIGIN;
try {
const u = new URL(base);
u.hostname = u.hostname.replace(/^rest\./, "app.");
return (u.origin + u.pathname).replace(/\/+$/, "");
} catch {
return DEFAULT_APP_ORIGIN;
}
}
function mcpEndpointFor(base: string | null, appBase: string | null = null): string {
const origin = appOrigin(base, appBase);
return origin === null ? `${HOST_PLACEHOLDER}/api/mcp` : `${origin}/api/mcp`;
}
function escapeHtml(s: string): string {
return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
}
/**
* Apply the configured base URL and API key to a sample. Pass `html: true` when `text`
* is shiki-highlighted HTML — there the `<api-key>` placeholder is entity-escaped to
* `<api-key>`, and the substituted key must be escaped too. The same applies to
* `<your-host>`: injected raw into highlighted HTML the browser would eat it as a tag,
* so it goes in entity-encoded and only the copy path (html: false) gets the literal.
*/
export function applyConfig(
text: string,
base: string | null,
apiKey: string,
html = false,
appBase: string | null = null
): string {
// A configured base is reader-supplied and can hold `&` or `'` (new URL() leaves
// both intact), so it needs the same escaping the api key gets — otherwise those
// decode inside the highlighted markup and render a host nobody typed.
const host = base ?? HOST_PLACEHOLDER;
const hostReplacement = html ? escapeHtml(host) : host;
let out = text;
if (hostReplacement !== DEFAULT_API_BASE) {
out = out.split(DEFAULT_API_BASE).join(hostReplacement);
}
const mcp = mcpEndpointFor(base, appBase);
out = out.split(DEFAULT_MCP_ENDPOINT).join(html ? escapeHtml(mcp) : mcp);
// Carbon API (`/api/v1/…`) samples are served by the APP, not the REST host, so
// they carry the app origin literally. Rewrite it after the MCP endpoint above —
// that one starts with the same origin, and replacing the longer, more specific
// needle first keeps this from cutting it in half.
const app = appOrigin(base, appBase);
if (app !== null && app !== DEFAULT_APP_ORIGIN) {
out = out.split(DEFAULT_APP_ORIGIN).join(html ? escapeHtml(app) : app);
} else if (app === null) {
const placeholder = html ? escapeHtml(HOST_PLACEHOLDER) : HOST_PLACEHOLDER;
out = out.split(DEFAULT_APP_ORIGIN).join(placeholder);
}
if (apiKey) {
if (html) {
const keyEsc = escapeHtml(apiKey);
// Shiki escapes only what HTML strictly requires, so the brackets around the
// placeholder come back INDEPENDENTLY encoded — in practice `<api-key>`,
// with the `<` a hex entity and the `>` left raw. Matching a fixed pair of
// fully-encoded needles silently missed that and shipped a sample that still
// said `<api-key>` after the reader had set one. Match either bracket in any
// of its forms instead.
const LT = "(?:<|<|<|<)";
const GT = "(?:>|>|>|>)";
out = out.replace(new RegExp(`${LT}api-key${GT}`, "gi"), keyEsc);
} else {
out = out.split(API_KEY_PLACEHOLDER).join(apiKey);
}
}
return out;
}