Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

14.0 KB
Raw Blame
import { z } from 'zod';

/**
 * Prefix marking an at-rest ciphertext. Mirrors ENCRYPTION_PREFIX in
 * `@openpanel/shared/server/encryption.ts`, duplicated because this file is
 * bundled for the browser and must not pull in the node-only crypto module.
 *
 * Credentials are WRITE-ONLY: the API redacts them on read, so a client never
 * legitimately holds one. Refusing the prefix on input stops a caller from
 * replaying a ciphertext lifted from another integration — `decryptCredential`
 * accepts any `enc:` blob under the single global key, so an accepted ciphertext
 * would be a portable bearer token.
 */
export const ENCRYPTED_SECRET_PREFIX = 'enc:';

export function looksEncrypted(value: string): boolean {
  return value.startsWith(ENCRYPTED_SECRET_PREFIX);
}

/**
 * A secret the client writes but never reads back. Empty means "keep whatever
 * is already stored" (enforced server-side: required on create, carried over on
 * update). An `enc:` value is always rejected — see ENCRYPTED_SECRET_PREFIX.
 */
const zWriteOnlySecret = (label: string) =>
  z.string().refine((value) => !looksEncrypted(value), {
    message: `${label} looks like a stored, already-encrypted value. Paste the real credential, or leave it blank to keep the current one.`,
  });

/** The only credential document shape we accept for GCS. */
export interface IServiceAccountKey {
  type: 'service_account';
  project_id: string;
  client_email: string;
  private_key: string;
  private_key_id?: string;
  universe_domain?: string;
}

export type IServiceAccountKeyResult =
  | { ok: true; credentials: IServiceAccountKey }
  | { ok: false; error: string };

/**
 * Parse and PIN a Google credential document to `type: "service_account"`.
 *
 * google-auth-library dispatches on the document's `type` field, and the other
 * branches are dangerous with tenant-supplied input: an `external_account`
 * document turns `credentials` into an arbitrary-file-read and SSRF primitive
 * (`credential_source.file` / `.url`, exfiltrated to an attacker-chosen
 * `token_url`, none of which the library validates). Never hand an unvalidated
 * document to the SDK — parse it here first, and pass only the allowlisted
 * fields on.
 */
export function parseServiceAccountKey(raw: string): IServiceAccountKeyResult {
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    return { ok: false, error: 'not valid JSON' };
  }

  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
    return { ok: false, error: 'not a JSON object' };
  }

  const doc = parsed as Record<string, unknown>;

  if (doc.type !== 'service_account') {
    return {
      ok: false,
      error: `unsupported credential type ${JSON.stringify(doc.type ?? null)} — only "service_account" keys are accepted`,
    };
  }

  for (const field of ['project_id', 'client_email', 'private_key'] as const) {
    if (typeof doc[field] !== 'string' || doc[field] === '') {
      return { ok: false, error: `missing "${field}"` };
    }
  }

  return {
    ok: true,
    credentials: {
      type: 'service_account',
      project_id: doc.project_id as string,
      client_email: doc.client_email as string,
      private_key: doc.private_key as string,
      ...(typeof doc.private_key_id === 'string'
        ? { private_key_id: doc.private_key_id }
        : {}),
      ...(typeof doc.universe_domain === 'string'
        ? { universe_domain: doc.universe_domain }
        : {}),
    },
  };
}

// Slack's persisted config is its OAuth token-exchange response
// (`oauth.v2.access`) plus our `type` tag. `./src/slack-contract.ts` derives
// `zSlackAuthResponse` from this schema so the two cannot drift.
export const zSlackConfig = z.object({
  type: z.literal('slack'),
  ok: z.literal(true),
  app_id: z.string(),
  authed_user: z.object({
    id: z.string(),
  }),
  scope: z.string(),
  token_type: z.literal('bot'),
  access_token: z.string(),
  bot_user_id: z.string(),
  team: z.object({
    id: z.string(),
    name: z.string(),
  }),
  incoming_webhook: z.object({
    channel: z.string(),
    channel_id: z.string(),
    configuration_url: z.string().url(),
    url: z.string().url(),
  }),
});
export type ISlackConfig = z.infer<typeof zSlackConfig>;

export const zWebhookConfig = z.object({
  type: z.literal('webhook'),
  url: z.string().url(),
  headers: z.record(z.string(), z.string()),
  payload: z.record(z.string(), z.unknown()).optional(),
  mode: z.enum(['message', 'javascript']).default('message'),
  javascriptTemplate: z.string().optional(),
});
export type IWebhookConfig = z.infer<typeof zWebhookConfig>;

export const zDiscordConfig = z.object({
  type: z.literal('discord'),
  // The webhook URL is a bearer credential, so it is write-only too: blank on
  // update keeps the stored one.
  url: z.string().url().or(z.literal('')),
});
export type IDiscordConfig = z.infer<typeof zDiscordConfig>;

export const zAppConfig = z.object({
  type: z.literal('app'),
});
export type IAppConfig = z.infer<typeof zAppConfig>;

export const zEmailConfig = z.object({
  type: z.literal('email'),
});
export type IEmailConfig = z.infer<typeof zEmailConfig>;

const zS3ExportConfigBase = z.object({
  type: z.literal('s3_export'),
  bucket: z.string().min(1, 'Bucket name is required'),
  prefix: z.string().default('openpanel-exports'),
  region: z.string().min(1, 'Region is required'),
  endpoint: z.string().url().optional(), // For R2, MinIO, etc.
  // Only jsonl_gzip is implemented; adding a format here without a
  // `createBatch` branch persists a config whose exports can never run.
  format: z.enum(['jsonl_gzip']).default('jsonl_gzip'),
  encryption: z.enum(['SSE-S3', 'SSE-KMS', 'none']).default('SSE-S3'),
  kmsKeyId: z.string().optional(),
});

// Auth mode: IAM Role assumption (AWS best practice)
const zS3AuthIamRole = z.object({
  authMode: z.literal('iam_role'),
  roleArn: z.string().min(1, 'IAM Role ARN is required'),
  externalId: z.string().optional(),
});

// Auth mode: Access Keys (for R2, MinIO, DigitalOcean Spaces, etc.)
const zS3AuthAccessKey = z.object({
  authMode: z.literal('access_key'),
  accessKeyId: z.string().min(1, 'Access Key ID is required'),
  // Write-only. Blank on update = keep the stored key (see zWriteOnlySecret).
  secretAccessKey: zWriteOnlySecret('Secret Access Key'),
});

export const zS3ExportConfigIamRole = zS3ExportConfigBase.merge(zS3AuthIamRole);
export type IS3ExportConfigIamRole = z.infer<typeof zS3ExportConfigIamRole>;

export const zS3ExportConfigAccessKey =
  zS3ExportConfigBase.merge(zS3AuthAccessKey);
export type IS3ExportConfigAccessKey = z.infer<typeof zS3ExportConfigAccessKey>;

export const zS3ExportConfig = z.discriminatedUnion('authMode', [
  zS3ExportConfigIamRole,
  zS3ExportConfigAccessKey,
]);
export type IS3ExportConfig = z.infer<typeof zS3ExportConfig>;

export const zGCSExportConfig = z.object({
  type: z.literal('gcs_export'),
  bucket: z.string().min(1, 'Bucket name is required'),
  prefix: z.string().default('openpanel-exports'),
  // Only jsonl_gzip is implemented; adding a format here without a
  // `createBatch` branch persists a config whose exports can never run.
  format: z.enum(['jsonl_gzip']).default('jsonl_gzip'),
  // Service account credentials (JSON key as string). Write-only; blank on
  // update = keep the stored key. Non-blank must be a real service-account
  // document — see parseServiceAccountKey for why the type is pinned.
  serviceAccountKey: zWriteOnlySecret('Service account key').superRefine(
    (value, ctx) => {
      if (value === '') {
        return;
      }
      const result = parseServiceAccountKey(value);
      if (!result.ok) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message: `Invalid service account key: ${result.error}`,
        });
      }
    }
  ),
});
export type IGCSExportConfig = z.infer<typeof zGCSExportConfig>;

// Explicit union, the source of truth for narrowing. Deriving it from the
// registry via z.infer can silently widen a member to `{ type: string }`; the
// registry is forced to match this union via `satisfies`.

export type IIntegrationConfig =
  | ISlackConfig
  | IDiscordConfig
  | IWebhookConfig
  | IAppConfig
  | IEmailConfig
  | IS3ExportConfig
  | IGCSExportConfig;

export type IIntegrationType = IIntegrationConfig['type'];

// Plugin descriptor registry: each integration declares its capabilities, setup
// style, config schema and catalog metadata once. The server and client
// registries are keyed by the same `type` and forced to cover the union.

export type IIntegrationKind = 'notification' | 'export';

export interface IIntegrationDescriptor<
  TType extends IIntegrationType = IIntegrationType,
  TSchema extends z.ZodTypeAny = z.ZodTypeAny,
> {
  type: TType;
  kinds: readonly IIntegrationKind[];
  // 'form' renders a config form; 'oauth' renders an install button and fills
  // the config via an OAuth callback.
  setup: 'form' | 'oauth';
  configSchema: TSchema;
  catalog: {
    name: string;
    description: string;
    // Pseudo-integrations (app/email) are dispatched by flags, not user-added.
    hidden?: boolean;
  };
}

export const slackDescriptor = {
  type: 'slack',
  kinds: ['notification'],
  setup: 'oauth',
  configSchema: zSlackConfig,
  catalog: {
    name: 'Slack',
    description:
      'Connect your Slack workspace to get notified when new issues are created.',
  },
} as const satisfies IIntegrationDescriptor<'slack', typeof zSlackConfig>;

export const discordDescriptor = {
  type: 'discord',
  kinds: ['notification'],
  setup: 'form',
  configSchema: zDiscordConfig,
  catalog: {
    name: 'Discord',
    description:
      'Connect your Discord server to get notified when new issues are created.',
  },
} as const satisfies IIntegrationDescriptor<'discord', typeof zDiscordConfig>;

export const webhookDescriptor = {
  type: 'webhook',
  kinds: ['notification'],
  setup: 'form',
  configSchema: zWebhookConfig,
  catalog: {
    name: 'Webhook',
    description:
      'Create a webhook to take actions in your own systems when new events are created.',
  },
} as const satisfies IIntegrationDescriptor<'webhook', typeof zWebhookConfig>;

export const appDescriptor = {
  type: 'app',
  kinds: ['notification'],
  setup: 'form',
  configSchema: zAppConfig,
  catalog: {
    name: 'Website',
    description: 'In-app notifications',
    hidden: true,
  },
} as const satisfies IIntegrationDescriptor<'app', typeof zAppConfig>;

export const emailDescriptor = {
  type: 'email',
  kinds: ['notification'],
  setup: 'form',
  configSchema: zEmailConfig,
  catalog: { name: 'Email', description: 'Email notifications', hidden: true },
} as const satisfies IIntegrationDescriptor<'email', typeof zEmailConfig>;

export const s3ExportDescriptor = {
  type: 's3_export',
  kinds: ['export'],
  setup: 'form',
  configSchema: zS3ExportConfig,
  catalog: {
    name: 'S3 Export',
    description:
      'Export events to Amazon S3 for loading into Redshift, Snowflake, Athena, or other data warehouses.',
  },
} as const satisfies IIntegrationDescriptor<
  's3_export',
  typeof zS3ExportConfig
>;

export const gcsExportDescriptor = {
  type: 'gcs_export',
  kinds: ['export'],
  setup: 'form',
  configSchema: zGCSExportConfig,
  catalog: {
    name: 'GCS Export',
    description:
      'Export events to Google Cloud Storage for loading into BigQuery or other data warehouses.',
  },
} as const satisfies IIntegrationDescriptor<
  'gcs_export',
  typeof zGCSExportConfig
>;

export const INTEGRATION_DESCRIPTORS = [
  slackDescriptor,
  discordDescriptor,
  webhookDescriptor,
  appDescriptor,
  emailDescriptor,
  s3ExportDescriptor,
  gcsExportDescriptor,
] as const;

const descriptorByType = new Map(
  INTEGRATION_DESCRIPTORS.map((d) => [d.type, d] as const)
);

export function isKind(
  config: Pick<IIntegrationConfig, 'type'> | { type?: string },
  kind: IIntegrationKind
): boolean {
  // Lenient lookup: used as a filter predicate over all integrations, including
  // rows whose config is still empty (e.g. a Slack integration before its OAuth
  // callback fills the config). Unknown/undefined types are simply not of `kind`.
  const descriptor = descriptorByType.get(config.type as IIntegrationType);
  return descriptor
    ? (descriptor.kinds as readonly IIntegrationKind[]).includes(kind)
    : false;
}

// Runtime parser for any integration config. A plain union (not
// discriminatedUnion) because the s3 schema is itself a union on `authMode`.
// Static narrowing always comes from the explicit IIntegrationConfig above.
export const zIntegrationConfig = z.union([
  zSlackConfig,
  zWebhookConfig,
  zDiscordConfig,
  zAppConfig,
  zEmailConfig,
  zS3ExportConfig,
  zGCSExportConfig,
]);

const zCreateIntegrationBase = z.object({
  id: z.string().optional(),
  name: z.string().min(1),
  projectId: z.string().min(1),
});

export const zCreateSlackIntegration = zCreateIntegrationBase;

export const zCreateWebhookIntegration = zCreateIntegrationBase.extend({
  config: zWebhookConfig,
});

export const zCreateDiscordIntegration = zCreateIntegrationBase.extend({
  config: zDiscordConfig,
});

export const zCreateS3ExportIntegration = zCreateIntegrationBase.merge(
  z.object({
    config: zS3ExportConfig,
  })
);

export const zCreateGCSExportIntegration = zCreateIntegrationBase.merge(
  z.object({
    config: zGCSExportConfig,
  })
);

// Compile-time guards: type aliases that fail `tsc` if an invariant breaks.

type Assert<T extends true> = T;
type Equal<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;

// Every member of the union must keep a *literal* `type` discriminant. If any
// widens to { type: string }, this drops it and the equality fails.
type LiteralDiscriminant<U> = U extends { type: infer T }
  ? string extends T
    ? never
    : U
  : never;
type _AssertLiteralDiscriminant = Assert<
  Equal<IIntegrationConfig, LiteralDiscriminant<IIntegrationConfig>>
>;

// The descriptor registry must cover exactly the union's types — no missing,
// no extra. Add a config variant but forget its descriptor → compile error.
type _DescriptorTypes = (typeof INTEGRATION_DESCRIPTORS)[number]['type'];
type _AssertDescriptorCoverage = Assert<
  Equal<IIntegrationType, _DescriptorTypes>
>;