Skip to content

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.

11.8 KB
Raw Blame
// 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;
}