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: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import type { Database } from "@carbon/database";
import { getLogger } from "@carbon/logger";
import type { SupabaseClient } from "@supabase/supabase-js";
import { resolveIntegrationSecrets } from "../../integrations/secrets";
import { buildRampIdempotencyKey, RampClient } from "./client";
import {
CARBON_PROVIDER_NAME,
isCarbonConnection,
linkedConnections,
type RampConnection,
RampSeatConflictError
} from "./connection-status";
import {
RampAccountingConnectionSchema,
type RampCredentials,
type RampCursors,
type RampIntegrationMetadata,
RampIntegrationMetadataSchema
} from "./models";
import {
clearRampConnectionState,
patchRampConnection,
patchRampCursor,
patchRampRefreshedTokens
} from "./state";
/**
* Server-only Ramp connection and authentication state. Every entry point takes
* a SERVICE-ROLE Supabase client plus a company id, resolves vaulted metadata,
* and constructs a refresh-capable {@link RampClient}.
*
* This module is server-only (it reaches the vault + a privileged client) and is
* exported via `@carbon/ee/ramp.server` — never import it from `config.tsx`.
*/
export const RAMP = "ramp";
const logger = getLogger("ee", "ramp");
// /********************************************************\
// * Metadata read/write *
// \********************************************************/
/**
* Read the RAW stored (secret-free) metadata for the company's Ramp integration.
* Returns `null` when the integration is not installed or not active.
*/
/**
* `includeInactive` exists for TEARDOWN only.
*
* The uninstall route deactivates the row BEFORE calling `onUninstall`, so a
* read that requires `active` returns null inside the very hook whose job is to
* tear down the remote side — which silently made `rampOnUninstall`'s webhook and
* accounting-connection deletes dead code, leaving both alive at Ramp forever
* (found during the push-only verification, 2026-09-25). An orphaned connection
* keeps holding Ramp's single accounting seat, which is the exact failure
* push-only mode exists to prevent.
*
* Every other caller must keep the default: an inactive integration must not
* sync, push, or report health.
*/
export type RampMetadataReadOptions = { includeInactive?: boolean };
export async function readStoredRampMetadata(
serviceRole: SupabaseClient<Database>,
companyId: string,
options: RampMetadataReadOptions = {}
): Promise<Record<string, unknown> | null> {
const { data, error } = await serviceRole
.from("companyIntegration")
.select("metadata, active")
.eq("id", RAMP)
.eq("companyId", companyId)
.maybeSingle();
if (error || !data) return null;
if (!data.active && !options.includeInactive) return null;
return (data.metadata as Record<string, unknown> | null) ?? {};
}
/**
* Advance a single Ramp sync cursor (`metadata.cursors.<key>`) without reading
* or replacing any sibling state.
*/
export async function advanceRampCursor(
serviceRole: SupabaseClient<Database>,
companyId: string,
key: keyof NonNullable<RampCursors>,
value: string
): Promise<void> {
await patchRampCursor(serviceRole, companyId, key, value);
}
/**
* Clear the stored `webhookId`, `connectionId`, and paired vaulted webhook
* secret. Called on uninstall so a later reinstall re-creates them at Ramp
* instead of trusting state that no longer exists there. Leaves every other
* sibling key (cursors, account-mapping config, OAuth secrets) untouched.
*/
export async function clearRampConnectionMetadata(
serviceRole: SupabaseClient<Database>,
companyId: string
): Promise<void> {
await clearRampConnectionState(serviceRole, companyId);
}
// /********************************************************\
// * Connection *
// \********************************************************/
/**
* Build a {@link RampClient} wired for OAuth2 token refresh: it carries Carbon's
* OAuth app credentials (from env, needed to run the `refresh_token` grant) and
* an `onTokensRefreshed` hook that persists a refreshed oauth2 access token back
* to the vault. Shared by every caller that constructs a client so none of them
* builds one that cannot refresh an expired oauth2 token.
*/
export function buildRampClient(
serviceRole: SupabaseClient<Database>,
companyId: string,
credentials: RampCredentials
): RampClient {
// Carbon's OAuth app — read lazily from process.env (importing @carbon/env
// here would eagerly validate unrelated required vars and break server-only
// tests).
const rampClientId = process.env.RAMP_CLIENT_ID;
const rampClientSecret = process.env.RAMP_CLIENT_SECRET;
const oauthApp =
rampClientId && rampClientSecret
? { clientId: rampClientId, clientSecret: rampClientSecret }
: undefined;
return new RampClient(credentials, {
oauthApp,
// Only oauth2 connections refresh; client-credentials mint fresh tokens.
onTokensRefreshed:
credentials.type === "oauth2"
? (tokens) => persistRefreshedRampTokens(serviceRole, companyId, tokens)
: undefined
});
}
/**
* Persist a refreshed oauth2 access token + expiry through the atomic path
* patch. Ramp does not rotate the refresh token, so it is left untouched.
*/
async function persistRefreshedRampTokens(
serviceRole: SupabaseClient<Database>,
companyId: string,
tokens: { accessToken: string; expiresAt: string }
): Promise<void> {
await patchRampRefreshedTokens(serviceRole, companyId, tokens);
}
/**
* Load the company's Ramp integration — a ready {@link RampClient} plus parsed
* metadata (vaulted secrets resolved). Returns `null` when Ramp is not
* installed/active or the metadata does not parse.
*/
export async function getRampIntegration(
serviceRole: SupabaseClient<Database>,
companyId: string,
options: RampMetadataReadOptions = {}
): Promise<{ client: RampClient; metadata: RampIntegrationMetadata } | null> {
const stored = await readStoredRampMetadata(serviceRole, companyId, options);
if (!stored) return null;
const resolved = await resolveIntegrationSecrets(
serviceRole,
companyId,
RAMP,
stored
);
const parsed = RampIntegrationMetadataSchema.safeParse(resolved);
if (!parsed.success) return null;
const client = buildRampClient(
serviceRole,
companyId,
parsed.data.credentials
);
return { client, metadata: parsed.data };
}
/**
* Exchange an OAuth authorization code (the Connect-flow callback) for oauth2
* credentials, using Carbon's registered Ramp OAuth app. The caller stores
* these via the atomic Ramp OAuth patch (which vaults the access + refresh
* tokens) and then runs `rampOnInstall`.
*/
export async function exchangeRampOAuthCode(
code: string,
redirectUri: string
): Promise<{
credentials: Extract<RampCredentials, { type: "oauth2" }>;
/**
* The scopes the token response ACTUALLY returned, when it said.
*
* RFC 6749 §3.3 lets an authorization server issue NARROWER scope than
* requested, and requires it to include `scope` when it does. So the requested
* list is an intention and this is the fact — recording the intention would
* make the UI claim capabilities the grant may not carry. Undefined when the
* response omitted it (which, per §3.3, means "as requested").
*/
grantedScopes?: string[];
}> {
const clientId = process.env.RAMP_CLIENT_ID;
const clientSecret = process.env.RAMP_CLIENT_SECRET;
if (!clientId || !clientSecret) {
throw new Error(
"Ramp OAuth is not configured (set RAMP_CLIENT_ID / RAMP_CLIENT_SECRET)"
);
}
// A placeholder access token just to construct the client; the exchange only
// uses the OAuth app credentials.
const client = new RampClient(
{ type: "oauth2", accessToken: "" },
{ oauthApp: { clientId, clientSecret } }
);
const tokens = await client.exchangeAuthorizationCode(code, redirectUri);
return {
credentials: {
type: "oauth2",
accessToken: tokens.accessToken,
refreshToken: tokens.refreshToken,
expiresAt: tokens.expiresAt
},
grantedScopes: tokens.scope?.split(" ").filter(Boolean)
};
}
/**
* Ensure a Ramp accounting connection exists for the company. Creates one with
* `remote_provider_name: "Carbon"` when `metadata.connectionId` is unset and
* stores the returned id back into the (secret-free) metadata column.
*/
export async function ensureRampConnection(
serviceRole: SupabaseClient<Database>,
companyId: string
): Promise<{ connectionId: string } | null> {
const integration = await getRampIntegration(serviceRole, companyId);
if (!integration) return null;
const { client, metadata } = integration;
if (metadata.connectionId) return { connectionId: metadata.connectionId };
/**
* Ramp permits exactly ONE accounting connection, and `POST /accounting/connection`
* RETURNS THE INCUMBENT rather than refusing when one already exists — verified
* live 2026-09-26, where a provider-mode install against a business whose seat
* was held by another system stored that system's connection id as its own.
*
* Carbon then believed it held the seat: it would push the chart of accounts,
* cost centers and projects into someone else's connection, confirm syncs
* against it, show a green healthcheck — and on uninstall DELETE it, which is
* the "worst possible uninstall side effect" this file already warns about.
*
* So look before creating. An incumbent that is not Carbon's is a refusal with
* an actionable message, not something to adopt.
*/
let existing: RampConnection[] = [];
try {
existing = linkedConnections(await client.getAccountingConnections());
} catch (err) {
// Unreadable: fall through to the create, whose response is checked below.
// A transient read failure must not block an otherwise valid install.
//
// But SAY so. This read IS the seat-conflict guard — without it the install
// proceeds behind only the weaker check on the create's response, and the
// failure mode it exists to prevent (adopting, then on uninstall DELETING,
// another system's accounting connection) has no other trace. A silent
// catch made "the strong check was skipped" unobservable.
logger.warning(
"Could not read Ramp accounting connections — creating without the seat-conflict check",
{ companyId, error: err instanceof Error ? err.message : String(err) }
);
}
const incumbent = existing.find(
(connection) => !isCarbonConnection(connection)
);
const ownExisting = existing.find(isCarbonConnection);
if (ownExisting?.id) {
// Carbon's own connection already exists — adopt it. This is the documented
// re-install / fresh-database case that previously needed a manual metadata
// edit to recover from.
await patchRampConnection(serviceRole, companyId, ownExisting.id);
return { connectionId: ownExisting.id };
}
if (incumbent) {
throw new RampSeatConflictError(
incumbent.remote_provider_name ?? undefined
);
}
const connection = RampAccountingConnectionSchema.parse(
await client.createAccountingConnection(
{ remote_provider_name: CARBON_PROVIDER_NAME },
// Entity-scoped idempotency key — one accounting connection per company, so
// a retried install cannot create a second one at Ramp.
buildRampIdempotencyKey({
companyId,
operation: "createAccountingConnection",
scope: companyId
})
)
);
// The create can still hand back an incumbent the read above missed (it may
// have failed, or the seat may have been taken in between). Storing an id
// without checking whose it is is the whole bug.
if (
connection.remote_provider_name &&
!isCarbonConnection(connection as RampConnection)
) {
throw new RampSeatConflictError(connection.remote_provider_name);
}
const connectionId = connection.connection_id ?? connection.id;
if (!connectionId) {
throw new Error("Ramp did not return a connection id");
}
await patchRampConnection(serviceRole, companyId, connectionId);
return { connectionId };
}