create-safest-tools 0.2.0

package/template/src/platform-registry-validation.ts

@@ -0,0 +1,367 @@
+import { ApiError } from "./report-http";
+import type { JsonObject, JsonValue } from "./workflow-platform-types";
+import { validateJsonSchemaValue } from "./workflow-expressions";
+
+export type ConnectionKind = "webhook" | "external_api" | "customer_worker" | "ai_provider" | "notification" | "email";
+export type CredentialStrategy = "none" | "static_header" | "bearer" | "hmac" | "oauth2_client_credentials" | "oauth2_authorization_code" | "mutual_tls" | "service_binding";
+export type ComponentKind = "built_in" | "webhook_enrichment" | "api_enrichment" | "workers_ai" | "specialist_agent" | "action" | "message";
+
+export interface ConnectionVersionInput {
+  baseUrl: string | null;
+  serviceBindingName: string | null;
+  allowedHosts: string[];
+  allowedMethods: string[];
+  allowedPathPrefixes: string[];
+  requestLimitBytes: number;
+  responseLimitBytes: number;
+  responseContentTypes: string[];
+  timeoutMs: number;
+  concurrencyLimit: number;
+  requestsPerWindow: number;
+  windowSeconds: number;
+  credentialStrategy: CredentialStrategy;
+  secretReference: string | null;
+  signingStrategy: JsonObject;
+  oauthConfiguration: JsonObject;
+}
+
+export interface ConnectionCreateInput {
+  key: string;
+  name: string;
+  description: string;
+  kind: ConnectionKind;
+  version: ConnectionVersionInput;
+}
+
+export interface ComponentVersionInput {
+  implementationKind: "built_in" | "webhook" | "external_api" | "workers_ai" | "specialist_agent" | "message_template";
+  implementationReference: string;
+  inputSchema: JsonObject;
+  outputSchema: JsonObject;
+  allowedInputFields: string[];
+  dataClassifications: string[];
+  connectionVersionId: string | null;
+  riskClass: "low" | "medium" | "high" | "critical";
+  timeoutPolicy: JsonObject;
+  retryPolicy: JsonObject;
+  cachePolicy: JsonObject;
+  concurrencyPolicy: JsonObject;
+  budgetPolicy: JsonObject;
+  approvalPolicy: JsonObject;
+  toolManifest: JsonValue[];
+  compatibility: JsonObject;
+}
+
+export interface ComponentCreateInput {
+  key: string;
+  name: string;
+  description: string;
+  kind: ComponentKind;
+  effectClass: "read_only" | "side_effecting";
+  ownerKind: "safest" | "customer";
+  version: ComponentVersionInput;
+}
+
+const keyPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const secretReferencePattern = /^(?:CONNECTION|OAUTH|ACTION|NOTIFICATION|EMAIL|AI)_[A-Z0-9_]{2,96}$/u;
+const hostPattern = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u;
+const methodSet = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+const connectionKinds = new Set<ConnectionKind>(["webhook", "external_api", "customer_worker", "ai_provider", "notification", "email"]);
+const credentialStrategies = new Set<CredentialStrategy>(["none", "static_header", "bearer", "hmac", "oauth2_client_credentials", "oauth2_authorization_code", "mutual_tls", "service_binding"]);
+const componentKinds = new Set<ComponentKind>(["built_in", "webhook_enrichment", "api_enrichment", "workers_ai", "specialist_agent", "action", "message"]);
+const implementationKinds = new Set<ComponentVersionInput["implementationKind"]>(["built_in", "webhook", "external_api", "workers_ai", "specialist_agent", "message_template"]);
+
+function object(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ApiError(400, "invalid_registry_configuration", `${name} must be an object.`);
+  return value as Record<string, unknown>;
+}
+
+function known(input: Record<string, unknown>, fields: readonly string[], name: string): void {
+  const unsupported = Object.keys(input).find((key) => !fields.includes(key));
+  if (unsupported) throw new ApiError(400, "invalid_registry_configuration", `${name} contains unsupported field ${unsupported}.`);
+}
+
+function text(value: unknown, name: string, minimum: number, maximum: number): string {
+  if (typeof value !== "string" || value.trim().length < minimum || value.trim().length > maximum || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new ApiError(400, "invalid_registry_configuration", `${name} must contain ${minimum} to ${maximum} safe characters.`);
+  }
+  return value.trim();
+}
+
+function integer(value: unknown, name: string, minimum: number, maximum: number): number {
+  if (!Number.isInteger(value) || Number(value) < minimum || Number(value) > maximum) throw new ApiError(400, "invalid_registry_configuration", `${name} must be an integer from ${minimum} to ${maximum}.`);
+  return Number(value);
+}
+
+function json(value: unknown, name: string, depth = 0): JsonValue {
+  if (depth > 20) throw new ApiError(400, "invalid_registry_configuration", `${name} is nested too deeply.`);
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) {
+    if (value.length > 500) throw new ApiError(400, "invalid_registry_configuration", `${name} contains too many entries.`);
+    return value.map((entry, index) => json(entry, `${name}[${index}]`, depth + 1));
+  }
+  if (value && typeof value === "object") {
+    const result: JsonObject = {};
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length > 500) throw new ApiError(400, "invalid_registry_configuration", `${name} contains too many fields.`);
+    for (const [key, entry] of entries) {
+      if (["__proto__", "prototype", "constructor"].includes(key)) throw new ApiError(400, "invalid_registry_configuration", `${name} contains a prohibited field.`);
+      result[key] = json(entry, `${name}.${key}`, depth + 1);
+    }
+    return result;
+  }
+  throw new ApiError(400, "invalid_registry_configuration", `${name} must contain JSON data.`);
+}
+
+function jsonObject(value: unknown, name: string): JsonObject {
+  const parsed = json(value ?? {}, name);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new ApiError(400, "invalid_registry_configuration", `${name} must be an object.`);
+  return parsed;
+}
+
+function stringList(value: unknown, name: string, maximum: number): string[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > maximum) throw new ApiError(400, "invalid_registry_configuration", `${name} must contain 1 to ${maximum} entries.`);
+  const result = value.map((entry, index) => text(entry, `${name}[${index}]`, 1, 300));
+  if (new Set(result).size !== result.length) throw new ApiError(400, "invalid_registry_configuration", `${name} contains duplicates.`);
+  return result;
+}
+
+function safeHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/gu, "").replace(/\.$/u, "");
+  if (!hostPattern.test(normalized) && !normalized.includes(":")) return false;
+  if (normalized === "localhost" || normalized.endsWith(".localhost") || normalized.endsWith(".local") || normalized.endsWith(".internal")) return false;
+  if (["metadata.google.internal", "metadata.aws.internal", "100.100.100.200", "169.254.169.254", "::1", "::"].includes(normalized)) return false;
+  const octets = normalized.split(".").map(Number);
+  if (octets.length === 4 && octets.every((octet) => Number.isInteger(octet) && octet >= 0 && octet <= 255)) {
+    const [a, b] = octets as [number, number, number, number];
+    if (a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127) || a >= 224) return false;
+  }
+  if (normalized.includes(":") && (/^(?:fc|fd|fe8|fe9|fea|feb)/u.test(normalized) || normalized.startsWith("::ffff:"))) return false;
+  return true;
+}
+
+function safeOauthUrl(value: unknown, field: string): string {
+  try {
+    const url = new URL(text(value, field, 1, 2_048));
+    if (url.protocol !== "https:" || url.username || url.password || url.hash || !safeHostname(url.hostname)) throw new Error("unsafe");
+    return url.href;
+  } catch {
+    throw new ApiError(400, "unsafe_oauth_url", `${field} must be a public HTTPS URL without credentials or a fragment.`);
+  }
+}
+
+function oauthConfiguration(value: unknown, strategy: CredentialStrategy): JsonObject {
+  const configuration = jsonObject(value ?? {}, "oauth_configuration");
+  if (strategy !== "oauth2_authorization_code") {
+    if (Object.keys(configuration).length) throw new ApiError(400, "invalid_oauth_configuration", "oauth_configuration is only supported for OAuth credential strategies.");
+    return configuration;
+  }
+  known(configuration, ["authorization_url", "token_url", "revoke_url", "client_id", "client_secret_reference", "scopes", "authorization_parameters"], "oauth_configuration");
+  const clientId = text(configuration.client_id, "oauth_configuration.client_id", 1, 500);
+  const clientSecretReference = configuration.client_secret_reference === undefined || configuration.client_secret_reference === null
+    ? null : text(configuration.client_secret_reference, "oauth_configuration.client_secret_reference", 3, 100);
+  if (clientSecretReference && !/^OAUTH_[A-Z0-9_]{2,96}$/u.test(clientSecretReference)) {
+    throw new ApiError(400, "invalid_secret_reference", "OAuth client secrets must use an OAUTH_ Worker secret binding.");
+  }
+  const scopes = configuration.scopes === undefined || (Array.isArray(configuration.scopes) && configuration.scopes.length === 0)
+    ? [] : stringList(configuration.scopes, "oauth_configuration.scopes", 100);
+  const parameters = jsonObject(configuration.authorization_parameters ?? {}, "oauth_configuration.authorization_parameters");
+  for (const [key, entry] of Object.entries(parameters)) {
+    if (!/^[A-Za-z0-9_.~-]{1,100}$/u.test(key) || typeof entry !== "string" || entry.length > 1_000
+      || ["state", "redirect_uri", "client_id", "code_challenge", "response_type"].includes(key)) {
+      throw new ApiError(400, "invalid_oauth_configuration", "authorization_parameters contains a reserved or unsafe value.");
+    }
+  }
+  return {
+    authorization_url: safeOauthUrl(configuration.authorization_url, "oauth_configuration.authorization_url"),
+    token_url: safeOauthUrl(configuration.token_url, "oauth_configuration.token_url"),
+    ...(configuration.revoke_url ? { revoke_url: safeOauthUrl(configuration.revoke_url, "oauth_configuration.revoke_url") } : {}),
+    client_id: clientId,
+    ...(clientSecretReference ? { client_secret_reference: clientSecretReference } : {}),
+    scopes,
+    authorization_parameters: parameters,
+  };
+}
+
+export function parseConnectionVersion(value: unknown): ConnectionVersionInput {
+  const input = object(value, "connection.version");
+  known(input, [
+    "base_url", "service_binding_name", "allowed_hosts", "allowed_methods", "allowed_path_prefixes",
+    "request_limit_bytes", "response_limit_bytes", "response_content_types", "timeout_ms", "concurrency_limit",
+    "requests_per_window", "window_seconds", "credential_strategy", "secret_reference",
+    "signing_strategy", "oauth_configuration",
+  ], "connection.version");
+  const serviceBindingName = input.service_binding_name === undefined || input.service_binding_name === null
+    ? null : text(input.service_binding_name, "service_binding_name", 2, 100);
+  let baseUrl: string | null = null;
+  let urlHost: string | null = null;
+  if (input.base_url !== undefined && input.base_url !== null) {
+    try {
+      const url = new URL(text(input.base_url, "base_url", 1, 2_048));
+      if (url.protocol !== "https:" || url.username || url.password || url.hash || url.search || !safeHostname(url.hostname)) throw new Error("unsafe");
+      baseUrl = url.href.endsWith("/") ? url.href.slice(0, -1) : url.href;
+      urlHost = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+    } catch {
+      throw new ApiError(400, "unsafe_connection_url", "base_url must be a public HTTPS origin without credentials, query, or fragment.");
+    }
+  }
+  if (Boolean(baseUrl) === Boolean(serviceBindingName)) throw new ApiError(400, "invalid_registry_configuration", "Exactly one of base_url or service_binding_name is required.");
+  const allowedHosts = baseUrl ? stringList(input.allowed_hosts ?? [urlHost], "allowed_hosts", 50).map((host) => host.toLowerCase()) : [];
+  if (allowedHosts.some((host) => !safeHostname(host)) || (urlHost && !allowedHosts.includes(urlHost))) throw new ApiError(400, "unsafe_connection_host", "allowed_hosts must contain only public hostnames and include base_url's host.");
+  const allowedMethods = stringList(input.allowed_methods ?? ["POST"], "allowed_methods", 6).map((method) => method.toUpperCase());
+  if (allowedMethods.some((method) => !methodSet.has(method))) throw new ApiError(400, "invalid_registry_configuration", "allowed_methods contains an unsupported method.");
+  const allowedPathPrefixes = stringList(input.allowed_path_prefixes ?? ["/"], "allowed_path_prefixes", 50);
+  if (allowedPathPrefixes.some((path) => !path.startsWith("/") || path.includes("..") || path.includes("?") || path.includes("#"))) throw new ApiError(400, "unsafe_connection_path", "allowed_path_prefixes contains an unsafe path.");
+  if (typeof input.credential_strategy !== "string" || !credentialStrategies.has(input.credential_strategy as CredentialStrategy)) throw new ApiError(400, "invalid_registry_configuration", "credential_strategy is unsupported.");
+  const credentialStrategy = input.credential_strategy as CredentialStrategy;
+  const secretReference = input.secret_reference === undefined || input.secret_reference === null ? null : text(input.secret_reference, "secret_reference", 3, 100);
+  if (secretReference && !secretReferencePattern.test(secretReference)) throw new ApiError(400, "invalid_secret_reference", "secret_reference must use an approved connection secret binding prefix.");
+  if (!["none", "oauth2_authorization_code"].includes(credentialStrategy) && !secretReference && credentialStrategy !== "service_binding") throw new ApiError(400, "connection_secret_required", "The selected credential strategy requires secret_reference.");
+  return {
+    baseUrl,
+    serviceBindingName,
+    allowedHosts,
+    allowedMethods,
+    allowedPathPrefixes,
+    requestLimitBytes: integer(input.request_limit_bytes ?? 65_536, "request_limit_bytes", 1, 1_048_576),
+    responseLimitBytes: integer(input.response_limit_bytes ?? 262_144, "response_limit_bytes", 1, 5_242_880),
+    responseContentTypes: stringList(input.response_content_types ?? ["application/json"], "response_content_types", 20),
+    timeoutMs: integer(input.timeout_ms ?? 5_000, "timeout_ms", 100, 120_000),
+    concurrencyLimit: integer(input.concurrency_limit ?? 8, "concurrency_limit", 1, 1_000),
+    requestsPerWindow: integer(input.requests_per_window ?? 60, "requests_per_window", 1, 1_000_000),
+    windowSeconds: integer(input.window_seconds ?? 60, "window_seconds", 1, 86_400),
+    credentialStrategy,
+    secretReference,
+    signingStrategy: jsonObject(input.signing_strategy ?? {}, "signing_strategy"),
+    oauthConfiguration: oauthConfiguration(input.oauth_configuration, credentialStrategy),
+  };
+}
+
+export function parseConnectionCreate(value: unknown): ConnectionCreateInput {
+  const input = object(value, "connection");
+  known(input, ["key", "name", "description", "kind", "version"], "connection");
+  const key = text(input.key, "connection.key", 2, 100);
+  if (!keyPattern.test(key)) throw new ApiError(400, "invalid_connection_key", "connection.key must be lower-case kebab-case.");
+  if (typeof input.kind !== "string" || !connectionKinds.has(input.kind as ConnectionKind)) throw new ApiError(400, "invalid_registry_configuration", "connection.kind is unsupported.");
+  return {
+    key,
+    name: text(input.name, "connection.name", 2, 160),
+    description: input.description === undefined ? "" : text(input.description, "connection.description", 0, 2_000),
+    kind: input.kind as ConnectionKind,
+    version: parseConnectionVersion(input.version),
+  };
+}
+
+function schema(value: unknown, name: string): JsonObject {
+  const result = jsonObject(value, name);
+  if (result.type !== "object" || !result.properties || typeof result.properties !== "object" || Array.isArray(result.properties)) {
+    throw new ApiError(400, "invalid_component_schema", `${name} must be an object JSON Schema with properties.`);
+  }
+  return result;
+}
+
+export function parseComponentVersion(value: unknown, effectClass?: "read_only" | "side_effecting"): ComponentVersionInput {
+  const input = object(value, "component.version");
+  known(input, [
+    "implementation_kind", "implementation_reference", "input_schema", "output_schema",
+    "allowed_input_fields", "data_classifications", "connection_version_id", "risk_class",
+    "timeout_policy", "retry_policy", "cache_policy", "concurrency_policy", "budget_policy",
+    "approval_policy", "tool_manifest", "compatibility",
+  ], "component.version");
+  if (typeof input.implementation_kind !== "string" || !implementationKinds.has(input.implementation_kind as ComponentVersionInput["implementationKind"])) throw new ApiError(400, "invalid_registry_configuration", "implementation_kind is unsupported.");
+  const connectionVersionId = input.connection_version_id === undefined || input.connection_version_id === null
+    ? null : text(input.connection_version_id, "connection_version_id", 1, 200);
+  if (["webhook", "external_api"].includes(input.implementation_kind) && !connectionVersionId) throw new ApiError(400, "component_connection_required", "Webhook and external API components must pin a connection version.");
+  const riskClass = input.risk_class ?? (effectClass === "side_effecting" ? "high" : "low");
+  if (!["low", "medium", "high", "critical"].includes(String(riskClass))) throw new ApiError(400, "invalid_registry_configuration", "risk_class is unsupported.");
+  const approvalPolicy = jsonObject(input.approval_policy ?? {}, "approval_policy");
+  if (effectClass === "side_effecting" && !["human", "bounded_auto"].includes(String(approvalPolicy.mode))) throw new ApiError(400, "action_approval_policy_required", "A side-effecting component requires a human or bounded_auto approval policy.");
+  const toolManifest = input.tool_manifest ?? [];
+  if (!Array.isArray(toolManifest)) throw new ApiError(400, "invalid_registry_configuration", "tool_manifest must be an array.");
+  const implementationReference = text(input.implementation_reference, "implementation_reference", 1, 300);
+  if (["webhook", "external_api"].includes(input.implementation_kind) && !/^(?:(?:GET|POST|PUT|PATCH|DELETE|HEAD)\s+)?\/[^\s]*$/u.test(implementationReference)) {
+    throw new ApiError(400, "component_operation_reference_invalid", "External component implementation_reference must be an optional HTTP method followed by an allowlisted absolute path.");
+  }
+  if (input.implementation_kind === "workers_ai" && !implementationReference.startsWith("@cf/")) {
+    throw new ApiError(400, "component_ai_model_invalid", "Workers AI component references must use an @cf model identifier.");
+  }
+  if (["built_in", "specialist_agent"].includes(input.implementation_kind) && !/^[a-z0-9]+(?:-[a-z0-9]+)*-v[1-9][0-9]*$/u.test(implementationReference)) {
+    throw new ApiError(400, "component_implementation_reference_invalid", "Built-in and specialist references must be immutable kebab-case version identifiers.");
+  }
+  const inputSchema = schema(input.input_schema, "input_schema");
+  const outputSchema = schema(input.output_schema, "output_schema");
+  const compatibility = jsonObject(input.compatibility ?? {}, "compatibility");
+  const fixtureEvidence = compatibility.fixture_evidence;
+  if (!fixtureEvidence || typeof fixtureEvidence !== "object" || Array.isArray(fixtureEvidence)) {
+    throw new ApiError(400, "component_fixture_evidence_invalid", "compatibility.fixture_evidence must contain server-verifiable fixtures.");
+  }
+  const fixturesValue = fixtureEvidence.fixtures;
+  if (!Array.isArray(fixturesValue) || fixturesValue.length < 1 || fixturesValue.length > 20) {
+    throw new ApiError(400, "component_fixture_evidence_invalid", "One to twenty component fixtures are required.");
+  }
+  const fixtureNames = new Set<string>();
+  const fixtures = fixturesValue.map((entry, index) => {
+    const fixture = object(entry, `compatibility.fixture_evidence.fixtures[${index}]`);
+    known(fixture, ["name", "input", "expected_output", "expected_status", "mode"], `compatibility.fixture_evidence.fixtures[${index}]`);
+    const name = text(fixture.name, `fixture[${index}].name`, 2, 120);
+    if (fixtureNames.has(name)) throw new ApiError(400, "component_fixture_evidence_invalid", "Fixture names must be unique.");
+    fixtureNames.add(name);
+    const fixtureInput = jsonObject(fixture.input, `fixture[${index}].input`);
+    const expectedOutput = jsonObject(fixture.expected_output ?? {}, `fixture[${index}].expected_output`);
+    const expectedStatus = fixture.expected_status === undefined ? "succeeded" : fixture.expected_status;
+    if (typeof expectedStatus !== "string" || !["succeeded", "failed", "timed_out"].includes(expectedStatus)) throw new ApiError(400, "component_fixture_evidence_invalid", "Fixture expected_status is invalid.");
+    const mode = fixture.mode ?? "simulated";
+    if (mode !== "simulated" && mode !== "live_dry_run") throw new ApiError(400, "component_fixture_evidence_invalid", "Fixture mode is invalid.");
+    const inputErrors = validateJsonSchemaValue(fixtureInput, inputSchema);
+    const outputErrors = expectedStatus === "succeeded" ? validateJsonSchemaValue(expectedOutput, outputSchema) : [];
+    if (inputErrors.length || outputErrors.length) throw new ApiError(422, "component_fixture_schema_invalid", "A component fixture does not match the published schemas.", { name, inputErrors, outputErrors });
+    return { name, input: fixtureInput, expected_output: expectedOutput, expected_status: expectedStatus, mode } as JsonObject;
+  });
+  compatibility.fixture_evidence = { passed: true, validated_by: "server", fixtures };
+  return {
+    implementationKind: input.implementation_kind as ComponentVersionInput["implementationKind"],
+    implementationReference,
+    inputSchema,
+    outputSchema,
+    allowedInputFields: stringList(input.allowed_input_fields, "allowed_input_fields", 100),
+    dataClassifications: stringList(input.data_classifications ?? ["report_operational"], "data_classifications", 20),
+    connectionVersionId,
+    riskClass: riskClass as ComponentVersionInput["riskClass"],
+    timeoutPolicy: jsonObject(input.timeout_policy ?? { timeout_ms: 5_000 }, "timeout_policy"),
+    retryPolicy: jsonObject(input.retry_policy ?? { maximum_attempts: 3, backoff: "exponential" }, "retry_policy"),
+    cachePolicy: jsonObject(input.cache_policy ?? { enabled: false }, "cache_policy"),
+    concurrencyPolicy: jsonObject(input.concurrency_policy ?? { maximum_concurrency: 8 }, "concurrency_policy"),
+    budgetPolicy: jsonObject(input.budget_policy ?? {}, "budget_policy"),
+    approvalPolicy,
+    toolManifest: toolManifest.map((entry, index) => json(entry, `tool_manifest[${index}]`)),
+    compatibility,
+  };
+}
+
+export function parseComponentCreate(value: unknown): ComponentCreateInput {
+  const input = object(value, "component");
+  known(input, ["key", "name", "description", "kind", "effect_class", "owner_kind", "version"], "component");
+  const key = text(input.key, "component.key", 2, 100);
+  if (!keyPattern.test(key)) throw new ApiError(400, "invalid_component_key", "component.key must be lower-case kebab-case.");
+  if (typeof input.kind !== "string" || !componentKinds.has(input.kind as ComponentKind)) throw new ApiError(400, "invalid_registry_configuration", "component.kind is unsupported.");
+  if (input.effect_class !== "read_only" && input.effect_class !== "side_effecting") throw new ApiError(400, "invalid_registry_configuration", "effect_class is unsupported.");
+  if (input.owner_kind !== "safest" && input.owner_kind !== "customer") throw new ApiError(400, "invalid_registry_configuration", "owner_kind is unsupported.");
+  if (input.kind === "action" && input.effect_class !== "side_effecting") throw new ApiError(400, "action_effect_class_required", "Action components must be side_effecting.");
+  if (input.kind !== "action" && input.effect_class === "side_effecting") throw new ApiError(400, "component_effect_mismatch", "Only action components may be side_effecting.");
+  return {
+    key,
+    name: text(input.name, "component.name", 2, 160),
+    description: input.description === undefined ? "" : text(input.description, "component.description", 0, 2_000),
+    kind: input.kind as ComponentKind,
+    effectClass: input.effect_class,
+    ownerKind: input.owner_kind,
+    version: parseComponentVersion(input.version, input.effect_class),
+  };
+}
+
+export function assertSafeConnectionDestination(url: URL, allowedHosts: string[], allowedPathPrefixes: string[]): void {
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+  if (url.protocol !== "https:" || url.username || url.password || !safeHostname(host) || !allowedHosts.includes(host)) throw new ApiError(400, "connection_destination_denied", "The connection destination is not allowlisted.");
+  if (!allowedPathPrefixes.some((prefix) => url.pathname.startsWith(prefix))) throw new ApiError(400, "connection_path_denied", "The connection path is not allowlisted.");
+}