@contractspec/bundle.library 3.9.10 → 3.10.0

package/src/components/integrations/helpers/credentialSetupAliases.ts

@@ -0,0 +1,137 @@
+import type {
+	IntegrationCredentialAlias,
+	IntegrationCredentialModeManifest,
+} from '@contractspec/lib.contracts-integrations';
+import type {
+	EnvironmentConfig,
+	EnvVariableAlias,
+} from '@contractspec/lib.contracts-spec/workspace-config/environment';
+import type {
+	BuildIntegrationCredentialSetupModelInput,
+	CredentialSetupAliasRow,
+	CredentialSetupWarning,
+} from './credentialSetupModel';
+
+export function buildAliases(
+	manifest: IntegrationCredentialModeManifest | undefined,
+	input: BuildIntegrationCredentialSetupModelInput,
+	secretKeys: Set<string>,
+	warnings: CredentialSetupWarning[]
+): CredentialSetupAliasRow[] {
+	return [
+		...fromManifestAliases(manifest?.envAliases ?? [], secretKeys, warnings),
+		...fromEnvironmentAliases(input.environment, input, secretKeys, warnings),
+	];
+}
+
+function fromManifestAliases(
+	aliases: IntegrationCredentialAlias[],
+	secretKeys: Set<string>,
+	warnings: CredentialSetupWarning[]
+) {
+	return aliases.flatMap((alias): CredentialSetupAliasRow[] => {
+		if (
+			secretKeys.has(alias.logicalKey) &&
+			isPublicAlias(alias.envVar, alias.public)
+		) {
+			warnings.push({
+				level: 'error',
+				fieldKey: alias.logicalKey,
+				message: `Unsafe public alias was omitted for secret field ${alias.logicalKey}.`,
+			});
+			return [];
+		}
+		return [
+			{
+				logicalKey: alias.logicalKey,
+				envName: alias.envVar,
+				targetId: alias.targetId,
+				public: isPublicAlias(alias.envVar, alias.public),
+				warning: alias.public ? 'Public client alias' : undefined,
+			},
+		];
+	});
+}
+
+function fromEnvironmentAliases(
+	environment: EnvironmentConfig | undefined,
+	input: BuildIntegrationCredentialSetupModelInput,
+	secretKeys: Set<string>,
+	warnings: CredentialSetupWarning[]
+) {
+	if (!environment) return [];
+	return Object.values(environment?.variables ?? {}).flatMap((definition) =>
+		(definition.aliases ?? [])
+			.filter((alias) => aliasMatchesInput(alias, environment, input))
+			.flatMap((alias): CredentialSetupAliasRow[] => {
+				const publicAlias =
+					isPublicAlias(alias.name) || isPublicExposure(alias.exposure);
+				if (secretKeys.has(definition.key) && publicAlias) {
+					warnings.push({
+						level: 'error',
+						fieldKey: definition.key,
+						message: `Unsafe public alias was omitted for secret field ${definition.key}.`,
+					});
+					return [];
+				}
+				return [
+					{
+						logicalKey: definition.key,
+						envName: alias.name,
+						targetId: alias.targetId,
+						targetLabel: targetLabel(environment, alias.targetId),
+						profile: alias.profile,
+						framework: alias.framework,
+						public: publicAlias,
+						warning: publicAlias ? 'Public client alias' : undefined,
+					},
+				];
+			})
+	);
+}
+
+function aliasMatchesInput(
+	alias: EnvVariableAlias,
+	environment: EnvironmentConfig,
+	input: BuildIntegrationCredentialSetupModelInput
+) {
+	if (
+		input.targetIds?.length &&
+		alias.targetId &&
+		!input.targetIds.includes(alias.targetId)
+	)
+		return false;
+	if (input.profile && alias.profile && alias.profile !== input.profile)
+		return false;
+	if (
+		!input.targetIds?.length &&
+		(alias.targetId || alias.profile || alias.framework)
+	)
+		return false;
+	if (alias.framework && alias.targetId) {
+		const framework = environment.targets?.[alias.targetId]?.framework;
+		if (framework && framework !== alias.framework) return false;
+	}
+	return true;
+}
+
+function targetLabel(
+	environment: EnvironmentConfig,
+	targetId: string | undefined
+) {
+	if (!targetId) return undefined;
+	const target = environment.targets?.[targetId];
+	return target?.packageName ?? target?.appId ?? target?.id ?? targetId;
+}
+
+function isPublicExposure(exposure: string | undefined) {
+	return exposure === 'public-client' || exposure === 'native-client';
+}
+
+function isPublicAlias(name: string, explicit?: boolean) {
+	return (
+		explicit === true ||
+		name.startsWith('NEXT_PUBLIC_') ||
+		name.startsWith('EXPO_PUBLIC_')
+	);
+}

package/src/components/integrations/helpers/credentialSetupModel.ts

@@ -0,0 +1,218 @@
+import type {
+	IntegrationCredentialFieldRef,
+	IntegrationCredentialManifest,
+	IntegrationCredentialModeManifest,
+	IntegrationOwnershipMode,
+	IntegrationSpec,
+} from '@contractspec/lib.contracts-integrations';
+import { getIntegrationCredentialManifest } from '@contractspec/lib.contracts-integrations';
+import type { EnvironmentConfig } from '@contractspec/lib.contracts-spec/workspace-config/environment';
+import { buildAliases } from './credentialSetupAliases';
+
+export type CredentialSetupFieldKind = 'config' | 'secret';
+export type CredentialSetupFieldStatus = 'configured' | 'missing' | 'optional';
+export type CredentialSetupWarningLevel = 'info' | 'warning' | 'error';
+
+export interface CredentialSetupFieldRow {
+	kind: CredentialSetupFieldKind;
+	key: string;
+	label: string;
+	description?: string;
+	required: boolean;
+	status: CredentialSetupFieldStatus;
+	secretRef?: string;
+	envVar?: string;
+}
+
+export interface CredentialSetupAliasRow {
+	logicalKey: string;
+	envName: string;
+	targetId?: string;
+	targetLabel?: string;
+	profile?: string;
+	framework?: string;
+	public: boolean;
+	warning?: string;
+}
+
+export interface CredentialSetupWarning {
+	level: CredentialSetupWarningLevel;
+	message: string;
+	fieldKey?: string;
+}
+
+export interface CredentialSetupModeOption {
+	mode: IntegrationOwnershipMode;
+	label: string;
+	available: boolean;
+	fieldCount: number;
+	missingRequiredCount: number;
+	docsUrl?: string;
+	setupSteps?: string[];
+}
+
+export interface IntegrationCredentialSetupModel {
+	selectedMode: IntegrationOwnershipMode;
+	modes: CredentialSetupModeOption[];
+	fields: CredentialSetupFieldRow[];
+	aliases: CredentialSetupAliasRow[];
+	warnings: CredentialSetupWarning[];
+}
+
+export interface BuildIntegrationCredentialSetupModelInput {
+	integration?: IntegrationSpec;
+	credentialManifest?: IntegrationCredentialManifest;
+	supportedModes?: IntegrationOwnershipMode[];
+	selectedMode?: IntegrationOwnershipMode;
+	environment?: EnvironmentConfig;
+	configValues?: Record<string, unknown>;
+	secretRefs?: Record<string, string | undefined>;
+	targetIds?: string[];
+	profile?: string;
+}
+
+export function buildIntegrationCredentialSetupModel(
+	input: BuildIntegrationCredentialSetupModelInput
+): IntegrationCredentialSetupModel {
+	const manifest = input.credentialManifest ?? manifestFromIntegration(input);
+	const supportedModes = resolveSupportedModes(input, manifest);
+	const selectedMode = input.selectedMode ?? supportedModes[0] ?? 'managed';
+	const modeManifest = manifest.modes?.[selectedMode];
+	const secretKeys = new Set(
+		(modeManifest?.secretFields ?? []).map((f) => f.key)
+	);
+	const warnings: CredentialSetupWarning[] = [];
+	const fields = buildFields(modeManifest, input, warnings);
+	const aliases = buildAliases(modeManifest, input, secretKeys, warnings);
+	const modes = supportedModes.map((mode) =>
+		buildModeOption(mode, manifest.modes?.[mode], input)
+	);
+
+	return { selectedMode, modes, fields, aliases, warnings };
+}
+
+function manifestFromIntegration(
+	input: BuildIntegrationCredentialSetupModelInput
+) {
+	return input.integration
+		? getIntegrationCredentialManifest(input.integration)
+		: {};
+}
+
+function resolveSupportedModes(
+	input: BuildIntegrationCredentialSetupModelInput,
+	manifest: IntegrationCredentialManifest
+): IntegrationOwnershipMode[] {
+	return (
+		input.supportedModes ??
+		input.integration?.supportedModes ??
+		(Object.keys(manifest.modes ?? {}) as IntegrationOwnershipMode[])
+	);
+}
+
+function buildModeOption(
+	mode: IntegrationOwnershipMode,
+	manifest: IntegrationCredentialModeManifest | undefined,
+	input: BuildIntegrationCredentialSetupModelInput
+): CredentialSetupModeOption {
+	const fields = [
+		...(manifest?.configFields ?? []),
+		...(manifest?.secretFields ?? []),
+	];
+	const missingRequiredCount = fields.filter(
+		(field) => field.required && !hasConfiguredField(field, input)
+	).length;
+	return {
+		mode,
+		label: mode === 'byok' ? 'BYOK' : 'Managed',
+		available: Boolean(manifest),
+		fieldCount: fields.length,
+		missingRequiredCount,
+		docsUrl: manifest?.docsUrl,
+		setupSteps: manifest?.setupSteps,
+	};
+}
+
+function buildFields(
+	manifest: IntegrationCredentialModeManifest | undefined,
+	input: BuildIntegrationCredentialSetupModelInput,
+	warnings: CredentialSetupWarning[]
+) {
+	const configRows = (manifest?.configFields ?? []).map((field) =>
+		buildFieldRow('config', field, input, warnings)
+	);
+	const secretRows = (manifest?.secretFields ?? []).map((field) =>
+		buildFieldRow('secret', field, input, warnings)
+	);
+	return [...configRows, ...secretRows];
+}
+
+function buildFieldRow(
+	kind: CredentialSetupFieldKind,
+	field: IntegrationCredentialFieldRef,
+	input: BuildIntegrationCredentialSetupModelInput,
+	warnings: CredentialSetupWarning[]
+): CredentialSetupFieldRow {
+	const configured = hasConfiguredField(field, input);
+	const secretRef =
+		kind === 'secret' ? safeSecretRef(field, input, warnings) : undefined;
+	if (kind === 'secret' && field.required === true && !configured) {
+		warnings.push({
+			level: 'warning',
+			fieldKey: field.key,
+			message: `${toLabel(field.key)} is required for BYOK secret reference setup.`,
+		});
+	}
+	return {
+		kind,
+		key: field.key,
+		label: toLabel(field.key),
+		description: field.description,
+		required: field.required === true,
+		status: configured ? 'configured' : field.required ? 'missing' : 'optional',
+		secretRef,
+		envVar: field.envVar,
+	};
+}
+
+function hasConfiguredField(
+	field: IntegrationCredentialFieldRef,
+	input: BuildIntegrationCredentialSetupModelInput
+) {
+	const configValue = input.configValues?.[field.key];
+	const secretRef =
+		input.secretRefs?.[field.key] ?? input.secretRefs?.[field.envVar ?? ''];
+	return hasPresence(configValue) || hasPresence(secretRef);
+}
+
+function safeSecretRef(
+	field: IntegrationCredentialFieldRef,
+	input: BuildIntegrationCredentialSetupModelInput,
+	warnings: CredentialSetupWarning[]
+) {
+	const value =
+		input.secretRefs?.[field.key] ?? input.secretRefs?.[field.envVar ?? ''];
+	if (!value) return undefined;
+	if (
+		/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ||
+		/^[A-Z][A-Z0-9_]*$/.test(value)
+	) {
+		return value;
+	}
+	warnings.push({
+		level: 'warning',
+		fieldKey: field.key,
+		message: `${toLabel(field.key)} has a value, but it is hidden because it is not a secret reference.`,
+	});
+	return undefined;
+}
+
+function hasPresence(value: unknown) {
+	return value !== undefined && value !== null && value !== '';
+}
+
+function toLabel(key: string) {
+	return key
+		.replace(/[_-]+/g, ' ')
+		.replace(/\b\w/g, (char) => char.toUpperCase());
+}

package/src/components/integrations/index.ts

@@ -1,3 +1,8 @@
+export * from './atoms/IntegrationCredentialFieldList';
+export * from './atoms/IntegrationCredentialModeTabs';
+export * from './atoms/IntegrationEnvAliasPreview';
+export * from './blocks/IntegrationCredentialSetupBlock';
+export * from './helpers/credentialSetupModel';
 export * from './molecules/IntegrationCard';
 export * from './organisms/IntegrationMarketplace';
 export * from './organisms/IntegrationSettings';

package/src/components/integrations/organisms/IntegrationSettings.tsx

@@ -1,4 +1,14 @@
-import { Button, Input, Textarea } from '@contractspec/lib.design-system';
+import {
+	Box,
+	Button,
+	HStack,
+	Input,
+	Muted,
+	Small,
+	Text,
+	Textarea,
+	VStack,
+} from '@contractspec/lib.design-system';
 import { Checkbox } from '@contractspec/lib.ui-kit-web/ui/checkbox';
 import { Label } from '@contractspec/lib.ui-kit-web/ui/label';
 import {
@@ -10,6 +20,9 @@ import {
 } from '@contractspec/lib.ui-kit-web/ui/select';
 import { Key, ShieldCheck, TestTube2 } from 'lucide-react';
 import * as React from 'react';
+import { IntegrationCredentialSetupBlock } from '../blocks/IntegrationCredentialSetupBlock';
+import type { BuildIntegrationCredentialSetupModelInput } from '../helpers/credentialSetupModel';
+import { IntegrationSettingsSecretReference } from './IntegrationSettingsSecretReference';
 
 export interface IntegrationSettingsForm {
 	apiKey: string;
@@ -27,6 +40,10 @@ export interface IntegrationSettingsProps {
 	onSave?: (values: IntegrationSettingsForm) => Promise<void> | void;
 	isSaving?: boolean;
 	isTesting?: boolean;
+	credentialSetup?: Omit<
+		BuildIntegrationCredentialSetupModelInput,
+		'selectedMode'
+	>;
 }
 
 export function IntegrationSettings({
@@ -36,6 +53,7 @@ export function IntegrationSettings({
 	onSave,
 	isSaving,
 	isTesting,
+	credentialSetup,
 }: IntegrationSettingsProps) {
 	const [values, setValues] = React.useState<IntegrationSettingsForm>({
 		apiKey: initialValues?.apiKey ?? '',
@@ -49,31 +67,31 @@ export function IntegrationSettings({
 	const handleChange = (
 		event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>
 	) => {
-		const target = event.target;
-		const { name, value } = target;
-		setValues((prev) => ({
-			...prev,
-			[name]: value,
-		}));
+		const { name, value } = event.target;
+		setValues((prev) => ({ ...prev, [name]: value }));
 	};
 
 	return (
-		<div className="space-y-4 rounded-2xl border border-border bg-card p-4">
-			<header className="flex flex-wrap items-center justify-between gap-3">
-				<div>
-					<p className="font-semibold text-sm uppercase tracking-wide">
-						{provider} credentials
-					</p>
-					<p className="text-muted-foreground text-sm">
+		<VStack
+			align="stretch"
+			gap="md"
+			className="rounded-2xl border border-border bg-card p-4"
+		>
+			<HStack wrap="wrap" justify="between" gap="md">
+				<VStack gap="sm" align="start">
+					<Small className="uppercase tracking-wide">{`${provider} credentials`}</Small>
+					<Muted>
 						Store encrypted keys with BYOK and run safe connection tests.
-					</p>
-				</div>
+					</Muted>
+				</VStack>
 				<ShieldCheck className="h-5 w-5 text-muted-foreground" />
-			</header>
+			</HStack>
 
-			<div className="grid gap-4 md:grid-cols-2">
-				<div className="space-y-2">
-					<Label htmlFor="ownershipMode">Ownership</Label>
+			<Box className="grid gap-4 md:grid-cols-2">
+				<VStack gap="sm" align="stretch">
+					<Label htmlFor="ownershipMode">
+						<Text>Ownership</Text>
+					</Label>
 					<Select
 						value={values.ownershipMode ?? 'managed'}
 						onValueChange={(next) =>
@@ -87,21 +105,34 @@ export function IntegrationSettings({
 							<SelectValue />
 						</SelectTrigger>
 						<SelectContent>
-							<SelectItem value="managed">Managed (store encrypted)</SelectItem>
+							<SelectItem value="managed">
+								<Text>Managed (store encrypted)</Text>
+							</SelectItem>
 							<SelectItem value="byok">
-								BYOK (store secret reference)
+								<Text>BYOK (store secret reference)</Text>
 							</SelectItem>
 						</SelectContent>
 					</Select>
-				</div>
-			</div>
+				</VStack>
+			</Box>
+
+			{credentialSetup ? (
+				<IntegrationCredentialSetupBlock
+					{...credentialSetup}
+					selectedMode={values.ownershipMode}
+					title={`${provider} setup`}
+					onModeChange={(mode) =>
+						setValues((prev) => ({ ...prev, ownershipMode: mode }))
+					}
+				/>
+			) : null}
 
-			<div className="grid gap-4 md:grid-cols-2">
-				<div className="space-y-1 text-sm">
+			<Box className="grid gap-4 md:grid-cols-2">
+				<VStack gap="sm" align="stretch">
 					<Label htmlFor="apiKey" className="font-semibold">
-						API key
+						<Text>API key</Text>
 					</Label>
-					<div className="relative">
+					<Box className="relative">
 						<Key className="pointer-events-none absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
 						<Input
 							type="text"
@@ -112,11 +143,11 @@ export function IntegrationSettings({
 							onChange={handleChange}
 							required
 						/>
-					</div>
-				</div>
-				<div className="space-y-1 text-sm">
+					</Box>
+				</VStack>
+				<VStack gap="sm" align="stretch">
 					<Label htmlFor="secret" className="font-semibold">
-						Secret
+						<Text>Secret</Text>
 					</Label>
 					<Input
 						type="password"
@@ -126,71 +157,34 @@ export function IntegrationSettings({
 						value={values.secret}
 						onChange={handleChange}
 					/>
-				</div>
-			</div>
+				</VStack>
+			</Box>
 
 			{values.ownershipMode === 'byok' ? (
-				<div className="space-y-4 rounded-xl border border-blue-500/20 bg-blue-500/5 p-4">
-					<p className="font-semibold text-sm">BYOK secret reference</p>
-					<div className="grid gap-4 md:grid-cols-2">
-						<div className="space-y-2">
-							<Label htmlFor="secretProvider">Secret provider</Label>
-							<Select
-								value={values.secretProvider ?? 'env'}
-								onValueChange={(next) =>
-									setValues((prev) => ({
-										...prev,
-										secretProvider:
-											next as IntegrationSettingsForm['secretProvider'],
-									}))
-								}
-							>
-								<SelectTrigger id="secretProvider" className="w-full">
-									<SelectValue />
-								</SelectTrigger>
-								<SelectContent>
-									<SelectItem value="env">Environment</SelectItem>
-									<SelectItem value="gcp">GCP Secret Manager</SelectItem>
-								</SelectContent>
-							</Select>
-						</div>
-						<div className="space-y-2">
-							<Label htmlFor="secretRef">Secret reference</Label>
-							<Input
-								id="secretRef"
-								name="secretRef"
-								placeholder={
-									values.secretProvider === 'gcp'
-										? 'gcp://projects/.../secrets/...'
-										: 'env://MY_TOKEN_ENV_VAR'
-								}
-								value={values.secretRef ?? ''}
-								onChange={handleChange}
-							/>
-						</div>
-					</div>
-				</div>
+				<IntegrationSettingsSecretReference
+					values={values}
+					onChange={handleChange}
+					onSecretProviderChange={(secretProvider) =>
+						setValues((prev) => ({ ...prev, secretProvider }))
+					}
+				/>
 			) : (
-				<div className="flex items-center gap-3 rounded-xl border border-emerald-500/20 bg-emerald-500/5 p-4 text-sm">
-					<Checkbox
-						checked
-						onCheckedChange={() => {
-							/* no-op */
-						}}
-						aria-label="Managed"
-					/>
-					<div>
-						<p className="font-semibold">Managed encryption enabled</p>
-						<p className="text-muted-foreground">
-							Secrets are encrypted server-side for this tenant.
-						</p>
-					</div>
-				</div>
+				<HStack
+					align="center"
+					gap="md"
+					className="rounded-xl border border-emerald-500/20 bg-emerald-500/5 p-4 text-sm"
+				>
+					<Checkbox checked onCheckedChange={() => {}} aria-label="Managed" />
+					<VStack gap="sm" align="start">
+						<Small>Managed encryption enabled</Small>
+						<Muted>Secrets are encrypted server-side for this tenant.</Muted>
+					</VStack>
+				</HStack>
 			)}
 
-			<div className="space-y-1 text-sm">
+			<VStack gap="sm" align="stretch">
 				<Label htmlFor="config" className="font-semibold">
-					Configuration (JSON)
+					<Text>Configuration (JSON)</Text>
 				</Label>
 				<Textarea
 					id="config"
@@ -199,25 +193,25 @@ export function IntegrationSettings({
 					value={values.config}
 					onChange={handleChange}
 				/>
-			</div>
+			</VStack>
 
-			<div className="flex flex-wrap items-center gap-3">
+			<HStack wrap="wrap" gap="md" align="center">
 				<Button
 					variant="ghost"
 					onPress={() => onTestConnection?.(values)}
 					disabled={isTesting}
 				>
 					<TestTube2 className="h-4 w-4" />
-					Test connection
+					<Text>Test connection</Text>
 				</Button>
 				<Button
 					variant="default"
 					onPress={() => onSave?.(values)}
 					disabled={isSaving}
 				>
-					Save settings
+					<Text>Save settings</Text>
 				</Button>
-			</div>
-		</div>
+			</HStack>
+		</VStack>
 	);
 }