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, Json as DatabaseJson } from "@carbon/database";
import type { SupabaseClient } from "@supabase/supabase-js";
/**
* Integration secret handling (NIST 800-171 3.13.16 / SC-28).
*
* Third-party credentials are encrypted at rest in Supabase Vault; only the
* non-secret configuration stays in the plaintext `companyIntegration.metadata`
* column. This module is the ONE place that declares which metadata keys are
* secret, plus the read/write helpers that move them in and out of the vault.
*
* The vault schema is not exposed to PostgREST, so all vault access goes through
* the SECURITY DEFINER RPCs added in the vault migration — always with a
* service-role client. A user (anon/authenticated) client cannot decrypt a
* secret.
*/
/**
* The ONLY declaration of which `metadata` keys hold secrets, per integration
* id. Dot-paths into the metadata object. Anything not listed here stays in the
* plaintext column (tenantId/realmId/sync config/etc.). A field mis-classified
* as non-secret leaks — keep this map exhaustive and reviewed.
*/
export const SECRET_KEYS: Record<string, string[]> = {
linear: ["apiKey", "webhookSigningSecret"],
mount: ["clientSecret"],
// slack: none — its token lives on integrationConnection (piece "slack").
jira: [
"credentials.accessToken",
"credentials.refreshToken",
"webhookSigningSecret"
],
onshape: ["credentials.accessToken", "credentials.refreshToken"],
// A Government customer's private OAuth app: its client secret is entered in
// the settings form, the tokens come from the callback.
"onshape-government": [
"clientSecret",
"credentials.accessToken",
"credentials.refreshToken"
],
"onshape-v2": ["credentials.accessToken", "credentials.refreshToken"],
xero: ["credentials.accessToken", "credentials.refreshToken"],
quickbooks: ["credentials.accessToken", "credentials.refreshToken"],
ramp: [
"credentials.clientSecret",
"credentials.accessToken",
"credentials.refreshToken",
"webhookSecret"
],
rillet: ["credentials.apiKey", "credentials.providerMetadata.webhookToken"],
"paperless-parts": ["apiKey", "secretKey"],
sense: ["apiKey"],
resend: ["apiKey"],
// email carries a secret in EITHER variant: Resend `apiKey` or SMTP `password`
// (top-level). splitSecrets omits whichever is absent for the active provider.
email: ["apiKey", "password"]
};
/**
* Metadata key of the OPTIONAL inbound-webhook signing secret for integrations
* whose webhook the customer creates by hand in the provider (Linear, Jira).
* Optional so existing unsigned installs keep working: when it is set, the
* webhook route rejects any delivery without a valid signature.
*/
export const WEBHOOK_SIGNING_SECRET_KEY = "webhookSigningSecret";
/** Thrown when a secret is expected in the vault but cannot be read (fail-closed). */
export class IntegrationSecretUnavailableError extends Error {
constructor(companyId: string, integrationId: string) {
super(
`Integration secret unavailable for ${integrationId} (company ${companyId})`
);
this.name = "IntegrationSecretUnavailableError";
}
}
type Json = Record<string, unknown>;
type CompanyIntegrationRow =
Database["public"]["Tables"]["companyIntegration"]["Row"];
export type IntegrationStatePatch = {
/** Flat dot-path map applied to the current plaintext metadata object. */
metadata?: Record<string, DatabaseJson | undefined>;
/** Flat dot-path map merged into the current Vault secret bag. */
secrets?: Record<string, DatabaseJson | undefined>;
removeMetadata?: string[];
removeSecrets?: string[];
active?: boolean;
updatedBy?: string;
};
/**
* Atomically patch one integration row and its Vault secret bag. The RPC locks
* the logical `(integrationId, companyId)` key and reads the current values
* inside the transaction; callers never submit a stale whole metadata object.
* Requires a SERVICE-ROLE client.
*/
export async function patchIntegrationState(
serviceClient: SupabaseClient<Database>,
companyId: string,
integrationId: string,
patch: IntegrationStatePatch
): Promise<CompanyIntegrationRow> {
const { data, error } = await serviceClient.rpc(
"upsert_company_integration_patch",
{
p_company_id: companyId,
p_integration_id: integrationId,
p_metadata_patch: patch.metadata ?? {},
p_secret_patch: patch.secrets ?? {},
p_metadata_remove: patch.removeMetadata ?? [],
p_secret_remove: patch.removeSecrets ?? [],
p_active: patch.active,
p_updated_by: patch.updatedBy
}
);
if (error) throw error;
if (!data || typeof data !== "object" || Array.isArray(data)) {
throw new Error(
`Integration state patch returned no row for ${integrationId} (company ${companyId})`
);
}
return data as CompanyIntegrationRow;
}
/** Read a dot-path (`a.b.c`) from a nested object; undefined if any hop is missing. */
export function getPath(obj: unknown, path: string): unknown {
const parts = path.split(".");
let cur: unknown = obj;
for (const part of parts) {
if (typeof cur !== "object" || cur === null) return undefined;
cur = (cur as Json)[part];
}
return cur;
}
/** Set a dot-path on a nested object, creating intermediate objects. Mutates `obj`. */
export function setPath(obj: Json, path: string, value: unknown): void {
const parts = path.split(".");
let cur: Json = obj;
for (let i = 0; i < parts.length - 1; i++) {
const part = parts[i]!;
if (typeof cur[part] !== "object" || cur[part] === null) {
cur[part] = {};
}
cur = cur[part] as Json;
}
cur[parts[parts.length - 1]!] = value;
}
/** Delete a dot-path leaf from a nested object. Mutates `obj`. Empty parents are left as-is. */
export function deletePath(obj: Json, path: string): void {
const parts = path.split(".");
let cur: Json = obj;
for (let i = 0; i < parts.length - 1; i++) {
const part = parts[i]!;
if (typeof cur[part] !== "object" || cur[part] === null) return;
cur = cur[part] as Json;
}
delete cur[parts[parts.length - 1]!];
}
/**
* Split a metadata object into the non-secret `config` (a deep copy with every
* SECRET_KEYS path removed) and a flat `secrets` bag (`{ [path]: value }`,
* omitting paths whose value is undefined). Unknown integration ids have no
* secret keys, so `config` is a pass-through and `secrets` is empty.
*/
export function splitSecrets(
integrationId: string,
metadata: unknown
): { config: Json; secrets: Record<string, unknown> } {
const config: Json =
typeof metadata === "object" && metadata !== null
? (structuredClone(metadata) as Json)
: {};
const secrets: Record<string, unknown> = {};
for (const path of SECRET_KEYS[integrationId] ?? []) {
const value = getPath(config, path);
// Anti-overwrite (D4a): an empty/absent value is "unchanged, don't write" —
// never persist it, so saving a form whose masked secret field was left
// untouched (submitted as "" or omitted) cannot clobber the vaulted secret.
if (value !== undefined && value !== "") {
secrets[path] = value;
}
// Always strip the path from config so the plaintext column never keeps a
// secret, even the empty placeholder.
deletePath(config, path);
}
return { config, secrets };
}
/**
* Persist an integration's secrets to the vault and write the stripped
* (non-secret) config to `companyIntegration.metadata`. Replaces any direct
* `metadata` write on a secret-bearing path. Requires a SERVICE-ROLE client.
* Returns the stripped config that was written to the column.
*/
export async function persistIntegrationSecrets(
serviceClient: SupabaseClient<Database>,
companyId: string,
integrationId: string,
metadata: unknown
): Promise<Json> {
const { config, secrets } = splitSecrets(integrationId, metadata);
// `secrets` is a PARTIAL bag — splitSecrets omits untouched masked fields — so
// the RPC MERGES it into the stored bag (an omitted secret keeps its value).
// A full replace silently wiped a multi-secret integration's other credential.
if (Object.keys(secrets).length > 0) {
const { error } = await serviceClient.rpc("upsert_integration_secret", {
p_company_id: companyId,
p_integration_id: integrationId,
p_secret: secrets as never
});
if (error)
throw new IntegrationSecretUnavailableError(companyId, integrationId);
}
const { error: updateError } = await serviceClient
.from("companyIntegration")
.update({ metadata: config as never })
.eq("companyId", companyId)
.eq("id", integrationId);
if (updateError) throw updateError;
return config;
}
/**
* Merge an integration's vaulted secrets back into a copy of its metadata so
* callers read the same shape as before (e.g. `metadata.credentials.accessToken`).
* Requires a SERVICE-ROLE client.
*
* - integration has no secret keys -> return metadata as-is (nothing to do).
* - `secretRef` set + vault returns the bag -> merged metadata.
* - `secretRef` set + vault returns null -> throw (fail-closed, D8).
* - secret-bearing integration + no `secretRef` -> throw (fail-closed): the
* plaintext has been scrubbed, so a missing vault pointer is a broken state,
* never "return the secret-free metadata as if complete". (The transitional
* plaintext fallback was removed with the backfill-and-scrub migration.)
*
* Pass `secretRef` from the row when you have it to skip the extra lookup.
*/
export async function resolveIntegrationSecrets(
serviceClient: SupabaseClient<Database>,
companyId: string,
integrationId: string,
metadata: unknown,
secretRef?: string | null
): Promise<Json> {
const base: Json =
typeof metadata === "object" && metadata !== null
? (structuredClone(metadata) as Json)
: {};
// Integrations that store no secrets have nothing to resolve.
if ((SECRET_KEYS[integrationId] ?? []).length === 0) return base;
let ref = secretRef;
if (ref === undefined) {
const { data } = await serviceClient
.from("companyIntegration")
.select("secretRef")
.eq("companyId", companyId)
.eq("id", integrationId)
.maybeSingle();
ref = data?.secretRef ?? null;
}
// Fail closed: a secret-bearing integration must carry a vault pointer.
if (!ref) {
throw new IntegrationSecretUnavailableError(companyId, integrationId);
}
const { data: bag, error } = await serviceClient.rpc(
"get_integration_secret",
{
p_company_id: companyId,
p_integration_id: integrationId
}
);
if (error || bag === null || typeof bag !== "object") {
throw new IntegrationSecretUnavailableError(companyId, integrationId);
}
for (const [path, value] of Object.entries(bag as Record<string, unknown>)) {
setPath(base, path, value);
}
return base;
}
/**
* Read an integration's optional webhook signing secret from the vault.
* Returns null when none is configured (the webhook stays unsigned). Throws
* `IntegrationSecretUnavailableError` when the vault cannot be read — callers
* must fail closed, since "no secret" cannot be told apart from "unreadable".
* Requires a SERVICE-ROLE client.
*/
export async function getWebhookSigningSecret(
serviceClient: SupabaseClient<Database>,
companyId: string,
integrationId: string,
row: { metadata: unknown; secretRef?: string | null }
): Promise<string | null> {
const resolved = await resolveIntegrationSecrets(
serviceClient,
companyId,
integrationId,
row.metadata,
row.secretRef
);
const secret = getPath(resolved, WEBHOOK_SIGNING_SECRET_KEY);
return typeof secret === "string" && secret.trim().length > 0
? secret.trim()
: null;
}