agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/run_ingest.py

@@ -0,0 +1,97 @@
+"""`agentcore run ingest` (port of the `ingest` subcommand in src/cli/commands/run/command.tsx)."""
+
+from __future__ import annotations
+
+import json
+import signal as signal_module
+import sys
+import threading
+
+import typer
+
+from agentcore.cli.groups import group
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib.errors.types import ValidationError
+from agentcore.lib.schemas.io.config_io import ConfigIO
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.operations.ingest import RunKbIngestionInput, run_kb_ingestion_by_name
+
+
+def _empty_state():  # readDeployedState().catch(() => ({ targets: {} }))
+    from agentcore.schema import DeployedState
+
+    return DeployedState(targets={})
+
+
+def run_ingest(name: str | None, target: str, data_source: str | None, as_json: bool) -> None:
+    if not name:
+        raise ValidationError("A --name is required for `agentcore run ingest`.")
+    target_name = target or "default"
+
+    config_io = ConfigIO()
+    project = config_io.read_project_spec()
+    aws_targets = config_io.read_aws_deployment_targets()
+    try:
+        deployed_state = config_io.read_deployed_state()
+    except Exception:  # noqa: BLE001 - missing/invalid state means nothing is deployed
+        deployed_state = _empty_state()
+
+    if not any(kb.name == name for kb in project.knowledge_bases or []):
+        raise ValidationError(f"Knowledge base '{name}' is not in agentcore.json.")
+    aws_target = next((t for t in aws_targets if t.name == target_name), None)
+    if aws_target is None:
+        raise ValidationError(f"Deployment target '{target_name}' is not in aws-targets.json.")
+
+    # Ctrl+C aborts long retry sleeps cleanly. Progress goes to stderr so --json stdout stays parseable.
+    abort = threading.Event()
+    previous = None
+    if threading.current_thread() is threading.main_thread():
+        previous = signal_module.signal(signal_module.SIGINT, lambda *_: abort.set())
+    try:
+        result = run_kb_ingestion_by_name(
+            RunKbIngestionInput(
+                knowledge_base_name=name,
+                deployed_state=deployed_state,
+                target_name=target_name,
+                region=aws_target.region,
+                data_source_uri=data_source,
+                signal=abort,
+                on_progress=None if as_json else (lambda msg: sys.stderr.write(f"{msg}\n")),
+            )
+        )
+    finally:
+        if previous is not None:
+            signal_module.signal(signal_module.SIGINT, previous)
+
+    if not result.success:
+        raise result.error
+
+    jobs = result.value.started_jobs
+    if as_json:
+        typer.echo(json.dumps({"success": True, "startedJobs": [j.to_json() for j in jobs]}, separators=(",", ":")))
+    else:
+        typer.echo(f"Started ingestion for '{name}' ({len(jobs)} data source(s)):")
+        for job in jobs:
+            typer.echo(f"  {job.uri}  →  {job.ingestion_job_id}")
+        typer.echo("\nRun 'agentcore status' to track progress.")
+
+
+def ingest_command(
+    name: str | None = typer.Option(None, "--name", help="Knowledge base name (must exist in agentcore.json)"),
+    target: str = typer.Option("default", "--target", help='Deployment target name (defaults to "default")'),
+    data_source: str | None = typer.Option(
+        None, "--data-source", help="Ingest only the data source with this URI (default: all sources)"
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+) -> None:
+    if not find_config_root():
+        typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+        raise typer.Exit(1)
+    run_cli_command(as_json, lambda: run_ingest(name, target, data_source, as_json))
+
+
+def register(app: typer.Typer) -> None:
+    group("run").command(
+        "ingest",
+        help="Start a fresh ingestion job for every data source on a deployed knowledge base.",
+    )(ingest_command)

agentcore/cli/commands/shared/arn_utils.py

@@ -0,0 +1,9 @@
+"""ARN shape check (port of src/cli/commands/shared/arn-utils.ts)."""
+
+_ARN_PART_COUNT = 6
+_ARN_FORMAT = "arn:partition:service:region:account:resource"
+ARN_VALIDATION_MESSAGE = f"Must be a valid ARN ({_ARN_FORMAT})"
+
+
+def is_valid_arn(value: str) -> bool:
+    return value.startswith("arn:") and len(value.split(":")) >= _ARN_PART_COUNT

agentcore/cli/commands/shared/filesystem_utils.py

@@ -0,0 +1,421 @@
+"""Filesystem mount helpers for runtimes (port of src/cli/commands/shared/filesystem-utils.ts).
+
+Mount entries are camelCase dicts, ready for agentcore.json:
+``{"accessPointArn": ..., "mountPath": ...}`` and ``{"volumeName": ..., "mountPath": ...}``.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from agentcore.aws.account import create_aws_client
+from agentcore.schema import EFS_ACCESS_POINT_ARN_PATTERN, S3_FILES_ACCESS_POINT_ARN_PATTERN
+from agentcore.schema._zod import js_regex
+
+_BYO_MOUNT_PATH = js_regex(r"^\/mnt\/[a-zA-Z0-9._-]+\/?$")
+
+
+@dataclass
+class MountsResult:
+    success: bool
+    mounts: list[dict[str, str]] = field(default_factory=list)
+    error: str | None = None
+
+
+@dataclass
+class SyncResult:
+    success: bool
+    error: str | None = None
+
+
+def _ok() -> SyncResult:
+    return SyncResult(True)
+
+
+def _fail(error: str) -> SyncResult:
+    return SyncResult(False, error)
+
+
+def _err_message(err: BaseException) -> str:
+    return str(err)
+
+
+# --- sync format checks -------------------------------------------------------------------------
+
+
+def validate_efs_access_point_arn(arn: str) -> Literal[True] | str:
+    if not EFS_ACCESS_POINT_ARN_PATTERN.search(arn):
+        return (
+            f'Invalid EFS access point ARN: "{arn}". Expected '
+            "arn:[partition]:elasticfilesystem:{region}:{account}:access-point/fsap-{id}"
+        )
+    return True
+
+
+def validate_s3_files_access_point_arn(arn: str) -> Literal[True] | str:
+    if not S3_FILES_ACCESS_POINT_ARN_PATTERN.search(arn):
+        return (
+            f'Invalid S3 Files access point ARN: "{arn}". Expected '
+            "arn:[partition]:s3files:{region}:{account}:file-system/fs-{id}/access-point/fsap-{id}"
+        )
+    return True
+
+
+def validate_byo_mount_path(path: str) -> Literal[True] | str:
+    """Validate a BYO filesystem mount path (/mnt/<name>)."""
+    if len(path) < 6 or len(path) > 200:
+        return f'Invalid mount path: "{path}". Must be between 6 and 200 characters'
+    if not _BYO_MOUNT_PATH.search(path):
+        return f'Invalid mount path: "{path}". Must be /mnt/<name> with exactly one subdirectory (e.g. /mnt/tools)'
+    return True
+
+
+def zip_access_point_pairs(
+    arns: Sequence[str], mount_paths: Sequence[str], label: Literal["EFS", "S3 Files"]
+) -> MountsResult:
+    if len(arns) != len(mount_paths):
+        arn_flag = "--efs-access-point-arn" if label == "EFS" else "--s3-access-point-arn"
+        path_flag = "--efs-mount-path" if label == "EFS" else "--s3-mount-path"
+        return MountsResult(
+            False,
+            error=(
+                f"{label}: {arn_flag} and {path_flag} must be provided in matching pairs "
+                f"(got {len(arns)} ARN(s) and {len(mount_paths)} path(s))"
+            ),
+        )
+    return MountsResult(True, [{"accessPointArn": a, "mountPath": p} for a, p in zip(arns, mount_paths, strict=True)])
+
+
+def zip_capacity_provider_volume_pairs(volume_names: Sequence[str], mount_paths: Sequence[str]) -> MountsResult:
+    if len(volume_names) != len(mount_paths):
+        return MountsResult(
+            False,
+            error=(
+                "Capacity provider volumes: --cp-volume-name and --cp-volume-mount-path must be provided in "
+                f"matching pairs (got {len(volume_names)} name(s) and {len(mount_paths)} path(s))"
+            ),
+        )
+    return MountsResult(
+        True, [{"volumeName": n, "mountPath": p} for n, p in zip(volume_names, mount_paths, strict=True)]
+    )
+
+
+def validate_capacity_provider_volume_mounts(mounts: Sequence[dict[str, str]]) -> SyncResult:
+    for mount in mounts:
+        name = mount.get("volumeName") or ""
+        if not name.strip():
+            return _fail("Capacity provider volume name must not be empty")
+        path_result = validate_byo_mount_path(mount.get("mountPath", ""))
+        if path_result is not True:
+            return _fail(path_result)
+    return _ok()
+
+
+def validate_access_point_mounts(
+    mounts: Sequence[dict[str, str]], arn_validator: Callable[[str], Literal[True] | str]
+) -> SyncResult:
+    for mount in mounts:
+        arn_result = arn_validator(mount["accessPointArn"])
+        if arn_result is not True:
+            return _fail(arn_result)
+        path_result = validate_byo_mount_path(mount["mountPath"])
+        if path_result is not True:
+            return _fail(path_result)
+    return _ok()
+
+
+def build_filesystem_configurations(
+    session_storage_mount_path: str | None = None,
+    efs_access_points: Sequence[dict[str, str]] | None = None,
+    s3_access_points: Sequence[dict[str, str]] | None = None,
+    capacity_provider_volumes: Sequence[dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """``{"filesystemConfigurations": [...]}`` when any mount is present, else ``{}``."""
+
+    def norm(p: str) -> str:
+        return p[:-1] if p.endswith("/") else p
+
+    fcs: list[dict[str, Any]] = []
+    if session_storage_mount_path:
+        fcs.append({"sessionStorage": {"mountPath": norm(session_storage_mount_path)}})
+    for ap in efs_access_points or []:
+        fcs.append({"efsAccessPoint": {**ap, "mountPath": norm(ap["mountPath"])}})
+    for ap in s3_access_points or []:
+        fcs.append({"s3FilesAccessPoint": {**ap, "mountPath": norm(ap["mountPath"])}})
+    for vol in capacity_provider_volumes or []:
+        fcs.append({"capacityProviderVolume": {**vol, "mountPath": norm(vol["mountPath"])}})
+    return {"filesystemConfigurations": fcs} if fcs else {}
+
+
+# --- async validators (Level 1-3) ---------------------------------------------------------------
+
+
+@dataclass
+class _MountTargetData:
+    mount_target_id: str
+    subnet_id: str
+    vpc_id: str
+    availability_zone_id: str | None
+    security_group_ids: list[str]
+
+
+def _region_from_arn(arn: str) -> str:
+    return arn.split(":")[3]
+
+
+def _access_point_id(arn: str) -> str:
+    return arn.split("/")[-1]
+
+
+def _allows_2049(rule: dict[str, Any]) -> bool:
+    proto = rule.get("IpProtocol")
+    from_port = rule.get("FromPort", 0)
+    to_port = rule.get("ToPort", 65535)
+    return proto == "-1" or (proto in ("tcp", "6") and from_port <= 2049 and to_port >= 2049)
+
+
+def _from_anywhere(rule: dict[str, Any]) -> bool:
+    return any(r.get("CidrIp") == "0.0.0.0/0" for r in rule.get("IpRanges") or []) or any(
+        r.get("CidrIpv6") == "::/0" for r in rule.get("Ipv6Ranges") or []
+    )
+
+
+def validate_efs_access_point_exists(arn: str, region: str) -> SyncResult:
+    """Level 1: the EFS access point exists (DescribeAccessPoints)."""
+    try:
+        client = create_aws_client("efs", region)
+        resp = client.describe_access_points(AccessPointId=_access_point_id(arn))
+        if not resp.get("AccessPoints"):
+            return _fail(f"EFS access point not found: {arn}")
+        return _ok()
+    except Exception as exc:  # noqa: BLE001
+        return _fail(f"EFS access point lookup failed for {arn}: {_err_message(exc)}")
+
+
+def validate_s3_files_access_point_exists(arn: str, region: str) -> SyncResult:
+    """Level 1: the S3 Files access point has mount targets (ListMountTargets)."""
+    try:
+        client = create_aws_client("s3files", region)
+        resp = client.list_mount_targets(accessPointId=_access_point_id(arn))
+        if not resp.get("mountTargets"):
+            return _fail(f"S3 Files access point has no mount targets: {arn}")
+        return _ok()
+    except Exception as exc:  # noqa: BLE001
+        return _fail(f"S3 Files access point lookup failed for {arn}: {_err_message(exc)}")
+
+
+def validate_security_group_egress_port_2049(security_group_ids: Sequence[str], region: str) -> SyncResult:
+    """Level 1: at least one agent SG allows outbound TCP 2049 (NFS)."""
+    try:
+        ec2 = create_aws_client("ec2", region)
+        resp = ec2.describe_security_groups(GroupIds=list(security_group_ids))
+        for sg in resp.get("SecurityGroups") or []:
+            for rule in sg.get("IpPermissionsEgress") or []:
+                has_destination = _from_anywhere(rule) or len(rule.get("UserIdGroupPairs") or []) > 0
+                if _allows_2049(rule) and has_destination:
+                    return _ok()
+        return _fail(
+            f"Agent security groups [{', '.join(security_group_ids)}] do not allow outbound TCP 2049 (NFS). "
+            "Add an egress rule for port 2049."
+        )
+    except Exception as exc:  # noqa: BLE001
+        return _fail(f"Security group egress check failed: {_err_message(exc)}")
+
+
+def _resolve_efs_data(arn: str, region: str) -> _MountTargetData | str:
+    try:
+        client = create_aws_client("efs", region)
+        mt_resp = client.describe_mount_targets(AccessPointId=_access_point_id(arn))
+        mts = mt_resp.get("MountTargets") or []
+        mt = mts[0] if mts else {}
+        if not mt.get("MountTargetId") or not mt.get("SubnetId") or not mt.get("VpcId"):
+            return f"EFS access point {arn} has no available mount targets"
+        sg_resp = client.describe_mount_target_security_groups(MountTargetId=mt["MountTargetId"])
+        return _MountTargetData(
+            mt["MountTargetId"],
+            mt["SubnetId"],
+            mt["VpcId"],
+            mt.get("AvailabilityZoneId"),
+            list(sg_resp.get("SecurityGroups") or []),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return f"Failed to resolve EFS mount target for {arn}: {_err_message(exc)}"
+
+
+def _resolve_s3_files_data(arn: str, region: str) -> _MountTargetData | str:
+    try:
+        client = create_aws_client("s3files", region)
+        list_resp = client.list_mount_targets(accessPointId=_access_point_id(arn))
+        mts = list_resp.get("mountTargets") or []
+        mt = mts[0] if mts else {}
+        if not mt.get("mountTargetId"):
+            return f"S3 Files access point {arn} has no available mount targets"
+        get_resp = client.get_mount_target(mountTargetId=mt["mountTargetId"])
+        if not get_resp.get("subnetId") or not get_resp.get("vpcId"):
+            return f"S3 Files mount target {mt['mountTargetId']} is missing subnet or VPC info"
+        return _MountTargetData(
+            mt["mountTargetId"],
+            get_resp["subnetId"],
+            get_resp["vpcId"],
+            get_resp.get("availabilityZoneId"),
+            list(get_resp.get("securityGroups") or []),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return f"Failed to resolve S3 Files mount target for {arn}: {_err_message(exc)}"
+
+
+def _validate_mount_target_in_vpc_and_az(
+    data: _MountTargetData, agent_subnet_ids: Sequence[str], agent_vpc_id: str, region: str, label: str
+) -> SyncResult:
+    """Level 2: mount target in the agent VPC, with an agent subnet in its AZ."""
+    if data.vpc_id != agent_vpc_id:
+        return _fail(f"{label} mount target VPC ({data.vpc_id}) does not match agent VPC ({agent_vpc_id})")
+    if not data.availability_zone_id:
+        return _ok()
+    try:
+        ec2 = create_aws_client("ec2", region)
+        resp = ec2.describe_subnets(SubnetIds=list(agent_subnet_ids))
+        agent_az_ids = {s.get("AvailabilityZoneId") for s in resp.get("Subnets") or [] if s.get("AvailabilityZoneId")}
+        if data.availability_zone_id not in agent_az_ids:
+            az = data.availability_zone_id
+            return _fail(
+                f"{label} mount target is in AZ {az} but no agent subnet is in that AZ. "
+                f"Add a subnet in AZ {az} to your agent configuration."
+            )
+    except Exception as exc:  # noqa: BLE001
+        return _fail(f"Subnet AZ validation failed for {label}: {_err_message(exc)}")
+    return _ok()
+
+
+def _validate_mount_target_inbound_from_agent_sg(
+    mount_sg_ids: Sequence[str], agent_sg_ids: Sequence[str], region: str, label: str
+) -> SyncResult:
+    """Level 3: mount target SGs allow inbound TCP 2049 from an agent SG."""
+    if not mount_sg_ids:
+        return _ok()
+    try:
+        ec2 = create_aws_client("ec2", region)
+        resp = ec2.describe_security_groups(GroupIds=list(mount_sg_ids))
+        agent_set = set(agent_sg_ids)
+        for sg in resp.get("SecurityGroups") or []:
+            for rule in sg.get("IpPermissions") or []:
+                if not _allows_2049(rule):
+                    continue
+                from_agent = any(p.get("GroupId") in agent_set for p in rule.get("UserIdGroupPairs") or [])
+                if from_agent or _from_anywhere(rule):
+                    return _ok()
+        return _fail(
+            f"{label} mount target security groups [{', '.join(mount_sg_ids)}] do not allow inbound TCP 2049 "
+            f"from agent security groups [{', '.join(agent_sg_ids)}]. Add an inbound rule for port 2049 from the "
+            "agent SG."
+        )
+    except Exception as exc:  # noqa: BLE001
+        return _fail(f"Mount target inbound SG check failed for {label}: {_err_message(exc)}")
+
+
+def validate_filesystem_mounts_configuration(
+    *,
+    efs_mounts: Sequence[dict[str, str]],
+    s3_files_mounts: Sequence[dict[str, str]],
+    region: str,
+    agent_vpc_id: str | None = None,
+    agent_subnet_ids: Sequence[str] | None = None,
+    agent_security_group_ids: Sequence[str] | None = None,
+    skip_topology_checks: bool = False,
+    skip_inbound_sg_checks: bool = False,
+) -> SyncResult:
+    """Levels 1-3 of filesystem validation; returns the first error. Levels lacking data are skipped."""
+    if agent_security_group_ids and (efs_mounts or s3_files_mounts):
+        egress = validate_security_group_egress_port_2049(agent_security_group_ids, region)
+        if not egress.success:
+            return egress
+
+    checks: list[tuple[Sequence[dict[str, str]], str, Callable[[str, str], SyncResult], Callable[..., Any]]] = [
+        (efs_mounts, "EFS", validate_efs_access_point_exists, _resolve_efs_data),
+        (s3_files_mounts, "S3 Files", validate_s3_files_access_point_exists, _resolve_s3_files_data),
+    ]
+    for mounts, label, exists, resolve in checks:
+        for mount in mounts:
+            arn = mount["accessPointArn"]
+            mount_region = _region_from_arn(arn)
+            result = exists(arn, mount_region)
+            if not result.success:
+                return result
+            if not skip_topology_checks and agent_vpc_id and agent_subnet_ids:
+                data = resolve(arn, mount_region)
+                if isinstance(data, str):
+                    return _fail(data)
+                vpc_result = _validate_mount_target_in_vpc_and_az(data, agent_subnet_ids, agent_vpc_id, region, label)
+                if not vpc_result.success:
+                    return vpc_result
+                if not skip_inbound_sg_checks and agent_security_group_ids:
+                    # Mount target SGs live in the mount's region, not the agent region.
+                    sg_result = _validate_mount_target_inbound_from_agent_sg(
+                        data.security_group_ids, agent_security_group_ids, mount_region, label
+                    )
+                    if not sg_result.success:
+                        return sg_result
+    return _ok()
+
+
+def resolve_and_validate_filesystem_mounts(
+    options: dict[str, Any],
+    parse_comma_separated_list: Callable[[str | None], list[str] | None],
+) -> dict[str, list[dict[str, str]]]:
+    """Zip CLI flag pairs, resolve the agent VPC from subnets and run Levels 1-3. Raises on failure."""
+    efs = zip_access_point_pairs(options.get("efsAccessPointArn") or [], options.get("efsMountPath") or [], "EFS")
+    if not efs.success:
+        raise Exception(efs.error)
+    s3 = zip_access_point_pairs(options.get("s3AccessPointArn") or [], options.get("s3MountPath") or [], "S3 Files")
+    if not s3.success:
+        raise Exception(s3.error)
+
+    if efs.mounts or s3.mounts:
+        region = (
+            options.get("region") or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or "us-east-1"
+        )
+        subnets = parse_comma_separated_list(options.get("subnets"))
+        security_groups = parse_comma_separated_list(options.get("securityGroups"))
+        agent_vpc_id: str | None = None
+        if subnets:
+            try:
+                ec2 = create_aws_client("ec2", region)
+                resp = ec2.describe_subnets(SubnetIds=list(subnets))
+                found = resp.get("Subnets") or []
+                agent_vpc_id = found[0].get("VpcId") if found else None
+            except Exception:  # noqa: BLE001 - Level 2 is skipped when the VPC can't be resolved
+                pass
+        result = validate_filesystem_mounts_configuration(
+            efs_mounts=efs.mounts,
+            s3_files_mounts=s3.mounts,
+            agent_vpc_id=agent_vpc_id,
+            agent_subnet_ids=subnets,
+            agent_security_group_ids=security_groups,
+            region=region,
+        )
+        if not result.success:
+            raise Exception(result.error)
+
+    return {"efsMounts": efs.mounts, "s3Mounts": s3.mounts}
+
+
+__all__ = [
+    "MountsResult",
+    "SyncResult",
+    "build_filesystem_configurations",
+    "resolve_and_validate_filesystem_mounts",
+    "validate_access_point_mounts",
+    "validate_byo_mount_path",
+    "validate_capacity_provider_volume_mounts",
+    "validate_efs_access_point_arn",
+    "validate_efs_access_point_exists",
+    "validate_filesystem_mounts_configuration",
+    "validate_s3_files_access_point_arn",
+    "validate_s3_files_access_point_exists",
+    "validate_security_group_egress_port_2049",
+    "zip_access_point_pairs",
+    "zip_capacity_provider_volume_pairs",
+]

agentcore/cli/commands/shared/header_utils.py

@@ -0,0 +1,87 @@
+"""Request header helpers (port of src/cli/commands/shared/header-utils.ts)."""
+
+import re
+from dataclasses import dataclass
+
+from agentcore.schema.schemas.agent_env import (
+    HEADER_ALLOWLIST_PREFIX,
+    HEADER_NAME_PATTERN,
+    MAX_HEADER_ALLOWLIST_SIZE,
+    check_allowlist_header,
+)
+
+__all__ = [
+    "HEADER_ALLOWLIST_PREFIX",
+    "HEADER_NAME_PATTERN",
+    "MAX_HEADER_ALLOWLIST_SIZE",
+    "HeaderValidationResult",
+    "normalize_header_name",
+    "parse_and_normalize_headers",
+    "parse_header_flag",
+    "parse_header_flags",
+    "validate_header_allowlist",
+]
+
+
+@dataclass
+class HeaderValidationResult:
+    success: bool
+    error: str | None = None
+
+
+def normalize_header_name(value: str) -> str:
+    if value.lower() == "authorization":
+        return "Authorization"
+    if value.lower().startswith(HEADER_ALLOWLIST_PREFIX.lower()):
+        return f"{HEADER_ALLOWLIST_PREFIX}{value[len(HEADER_ALLOWLIST_PREFIX) :]}"
+    if re.match(r"^x-", value, re.IGNORECASE):
+        return value
+    return f"{HEADER_ALLOWLIST_PREFIX}{value}"
+
+
+def parse_and_normalize_headers(value: str) -> list[str]:
+    """Split, normalize and de-duplicate (case-insensitively) a comma-separated header list."""
+    seen: set[str] = set()
+    result: list[str] = []
+    for header in (normalize_header_name(s.strip()) for s in value.split(",") if s.strip()):
+        if header.lower() not in seen:
+            seen.add(header.lower())
+            result.append(header)
+    return result
+
+
+def validate_header_allowlist(value: str) -> HeaderValidationResult:
+    trimmed = value.strip()
+    if trimmed == "":
+        return HeaderValidationResult(True)
+    names = [s.strip() for s in trimmed.split(",") if s.strip()]
+    for name in names:
+        error = check_allowlist_header(name)
+        if error:
+            return HeaderValidationResult(False, error)
+    if len(names) > MAX_HEADER_ALLOWLIST_SIZE:
+        return HeaderValidationResult(
+            False, f"Header allowlist cannot exceed {MAX_HEADER_ALLOWLIST_SIZE} headers. Provided: {len(names)}"
+        )
+    return HeaderValidationResult(True)
+
+
+def parse_header_flag(raw: str) -> tuple[str, str] | None:
+    """Parse "Key: Value" into (normalized name, value); None when malformed."""
+    idx = raw.find(":")
+    if idx < 1:
+        return None
+    name = raw[:idx].strip()
+    if not name:
+        return None
+    return normalize_header_name(name), raw[idx + 1 :].strip()
+
+
+def parse_header_flags(raw_headers: list[str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for raw in raw_headers:
+        parsed = parse_header_flag(raw)
+        if parsed is None:
+            raise ValueError(f'Invalid header format: "{raw}". Expected "Header-Name: value" or "Header-Name:value".')
+        result[parsed[0]] = parsed[1]
+    return result