Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /dislovelhl_enhanced-agent-bus /bundle_registry.py
"""
ACGS-2 OCI Bundle Registry Client
Constitutional Hash: 608508a9bd224290
Production-grade OCI registry integration for policy bundle distribution.
Supports Harbor, AWS ECR, GCR, and generic OCI-compliant registries.
"""
import asyncio
import hashlib
import json
import os
import tempfile
import threading
from abc import ABC, abstractmethod
from collections.abc import Coroutine
from dataclasses import dataclass, field
from datetime import UTC, datetime
from enum import Enum
from pathlib import Path
from typing import TypeVar
from urllib.parse import urlparse
import httpx
import jsonschema
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric import ed25519
try:
from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH
except ImportError:
CONSTITUTIONAL_HASH = "standalone"
from enhanced_agent_bus._compat.errors import (
ConstitutionalViolationError,
DataIntegrityError,
)
from enhanced_agent_bus._compat.errors import (
ValidationError as ACGSValidationError,
)
try:
from enhanced_agent_bus._compat.types import JSONDict
except ImportError:
JSONDict = dict # type: ignore[misc,assignment]
from enhanced_agent_bus.observability.structured_logging import get_logger
from enhanced_agent_bus.signing_provider import (
LocalEd25519SigningProvider,
SigningProvider,
resolve_signing_provider,
)
logger = get_logger(__name__)
T = TypeVar("T")
class RegistryType(Enum):
"""Supported OCI registry types."""
HARBOR = "harbor"
ECR = "ecr"
GCR = "gcr"
ACR = "acr"
GENERIC = "generic"
class BundleStatus(Enum):
"""Bundle lifecycle status."""
DRAFT = "draft"
PENDING_REVIEW = "pending_review"
APPROVED = "approved"
PUBLISHED = "published"
REVOKED = "revoked"
@dataclass
class BundleManifest:
"""
OCI-compliant bundle manifest following ACGS-2 schema.
Conforms to: policies/schema/bundle-manifest.schema.json
"""
version: str
revision: str # 40-char git SHA
constitutional_hash: str = CONSTITUTIONAL_HASH
timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
roots: list[str] = field(default_factory=lambda: ["acgs/governance"])
signatures: list[dict[str, str]] = field(default_factory=list)
metadata: JSONDict = field(default_factory=dict)
_schema: JSONDict | None = None
def __post_init__(self) -> None:
if self.constitutional_hash != CONSTITUTIONAL_HASH:
raise ConstitutionalViolationError(
f"Invalid constitutional hash. Expected {CONSTITUTIONAL_HASH}, "
f"got {self.constitutional_hash}",
error_code="BUNDLE_HASH_MISMATCH",
)
self.validate()
def validate(self) -> None:
"""Validate manifest against JSON schema."""
if not self._schema:
schema_path = os.path.join(
os.path.dirname(__file__), "../policies/schema/bundle-manifest.schema.json"
)
if os.path.exists(schema_path):
self._schema = self._run_async_io(self._read_schema(schema_path))
else:
logger.warning(
f"Schema file not found at {schema_path}, skipping strict validation"
)
return
try:
jsonschema.validate(instance=self.to_dict(), schema=self._schema)
except jsonschema.exceptions.ValidationError as e:
raise ACGSValidationError(
f"Manifest validation failed: {e.message}",
error_code="BUNDLE_MANIFEST_INVALID",
) from e
async def _read_schema(self, schema_path: str) -> JSONDict:
content = await asyncio.to_thread(Path(schema_path).read_text)
return json.loads(content)
@staticmethod
def _run_async_io(coro: Coroutine[object, object, T]) -> T:
try:
asyncio.get_running_loop()
except RuntimeError:
return asyncio.run(coro)
result: dict[str, T] = {}
error: dict[str, BaseException] = {}
def _runner() -> None:
try:
result["value"] = asyncio.run(coro)
except BaseException as exc: # pragma: no cover
error["exc"] = exc
thread = threading.Thread(target=_runner, daemon=False)
thread.start()
thread.join()
if "exc" in error:
raise error["exc"]
return result["value"]
def to_dict(self) -> JSONDict:
"""Convert to dictionary for JSON serialization."""
return {
"version": self.version,
"revision": self.revision,
"timestamp": self.timestamp,
"constitutional_hash": self.constitutional_hash,
"roots": self.roots,
"signatures": self.signatures,
"metadata": self.metadata,
}
@classmethod
def from_dict(cls, data: JSONDict) -> "BundleManifest":
"""Create manifest from dictionary."""
return cls(
version=data["version"],
revision=data["revision"],
constitutional_hash=data.get("constitutional_hash", CONSTITUTIONAL_HASH),
timestamp=data.get("timestamp", datetime.now(UTC).isoformat()),
roots=data.get("roots", []),
signatures=data.get("signatures", []),
metadata=data.get("metadata", {}),
)
def add_signature(self, keyid: str, signature: str, algorithm: str = "ed25519") -> None:
"""Add a signature to the manifest."""
self.signatures.append(
{
"keyid": keyid,
"sig": signature,
"alg": algorithm,
"timestamp": datetime.now(UTC).isoformat(),
}
)
def verify_signature(self, public_key_hex: str) -> bool:
"""
Verify manifest signatures using the provided public key.
Supports both standard ED25519 signatures and Cosign-compatible format.
Returns true if at least one signature is valid.
"""
if not self.signatures:
logger.warning("No signatures found in manifest")
return False
try:
public_key = ed25519.Ed25519PublicKey.from_public_bytes(bytes.fromhex(public_key_hex))
except (ValueError, TypeError, OSError) as e:
logger.error(f"Invalid public key format: {e}")
return False
# Digest for signing/verification excludes the signatures themselves
manifest_data = self.to_dict()
signatures = manifest_data.pop("signatures", [])
content = json.dumps(manifest_data, sort_keys=True).encode()
valid_count = 0
for sig_entry in signatures:
alg = sig_entry.get("alg", "ed25519")
# Support ED25519 (standard) and Cosign-compatible formats
if alg not in ("ed25519", "rsa-pss-sha256", "ecdsa-p256-sha256"):
continue
try:
sig_bytes = bytes.fromhex(sig_entry["sig"])
# For Cosign compatibility, verify against manifest digest
# Cosign signs the manifest digest, not the raw content
if alg == "ed25519":
# Standard ED25519 verification
public_key.verify(sig_bytes, content)
else:
# For other algorithms, we'd need additional crypto libraries
# For now, log and skip (can be extended later)
continue
valid_count += 1
logger.info(f"Valid signature found for key {sig_entry['keyid']} (alg: {alg})")
except (InvalidSignature, ValueError) as e:
logger.warning(f"Signature verification failed for key {sig_entry['keyid']}: {e}")
return valid_count > 0
def verify_cosign_signature(self, manifest_digest: str, public_key_hex: str) -> bool:
"""
Verify Cosign-compatible signature artifact.
Cosign signs the manifest digest (Docker-Content-Digest) rather than
the manifest content itself. This method verifies that signature.
Args:
manifest_digest: The Docker-Content-Digest of the manifest
public_key_hex: ED25519 public key in hex format
Returns:
True if signature is valid
"""
if not self.signatures:
logger.warning("No signatures found for Cosign verification")
return False
try:
public_key = ed25519.Ed25519PublicKey.from_public_bytes(bytes.fromhex(public_key_hex))
except (ValueError, TypeError, OSError) as e:
logger.error(f"Invalid public key format: {e}")
return False
# Cosign signs the manifest digest
digest_bytes = manifest_digest.encode()
valid_count = 0
for sig_entry in self.signatures:
if sig_entry.get("alg") != "ed25519":
continue
try:
sig_bytes = bytes.fromhex(sig_entry["sig"])
public_key.verify(sig_bytes, digest_bytes)
valid_count += 1
logger.info(f"Valid Cosign signature found for key {sig_entry['keyid']}")
except (InvalidSignature, ValueError) as e:
logger.warning(
f"Cosign signature verification failed for key {sig_entry['keyid']}: {e}"
)
return valid_count > 0
def compute_digest(self) -> str:
"""Compute SHA256 digest of manifest content."""
content = json.dumps(self.to_dict(), sort_keys=True).encode()
return hashlib.sha256(content).hexdigest()
@dataclass
class BundleArtifact:
"""Represents an OCI artifact containing a policy bundle."""
digest: str
size: int
media_type: str = "application/vnd.opa.bundle.layer.v1+gzip"
manifest: BundleManifest | None = None
annotations: dict[str, str] = field(default_factory=dict)
class RegistryAuthProvider(ABC):
"""Abstract base for registry authentication."""
@abstractmethod
async def get_token(self) -> str:
"""Get authentication token."""
pass
@abstractmethod
async def refresh_token(self) -> str:
"""Refresh expired token."""
pass
class BasicAuthProvider(RegistryAuthProvider):
"""
Basic username/password authentication with encrypted credential storage.
Credentials are encrypted in memory using Fernet symmetric encryption
to prevent exposure in memory dumps, debugging, or error traces.
"""
def __init__(self, username: str, password: str):
# Import Fernet for credential encryption
from cryptography.fernet import Fernet
# Generate a session-specific encryption key
# This key lives only in memory and changes each instantiation
self._cipher_key = Fernet.generate_key()
self._cipher = Fernet(self._cipher_key)
# Encrypt credentials immediately - never store plaintext
self._encrypted_username = self._cipher.encrypt(username.encode())
self._encrypted_password = self._cipher.encrypt(password.encode())
# Clear the plaintext from local scope (defense in depth)
del username, password
self._token: str | None = None
@property
def username(self) -> str:
"""Decrypt username on demand."""
return str(self._cipher.decrypt(self._encrypted_username).decode())
@property
def password(self) -> str:
"""Decrypt password on demand."""
return str(self._cipher.decrypt(self._encrypted_password).decode())
async def get_token(self) -> str:
if not self._token:
import base64
# Decrypt credentials only when needed
credentials = f"{self.username}:{self.password}"
self._token = base64.b64encode(credentials.encode()).decode()
return self._token
async def refresh_token(self) -> str:
self._token = None
return await self.get_token()
class AWSECRAuthProvider(RegistryAuthProvider):
"""AWS ECR authentication using boto3."""
def __init__(self, region: str = "us-east-1", profile: str | None = None):
self.region = region
self.profile = profile
self._token: str | None = None
self._expiry: datetime | None = None
async def get_token(self) -> str:
if self._token and self._expiry and datetime.now(UTC) < self._expiry:
return self._token
return await self.refresh_token()
async def refresh_token(self) -> str:
try:
import boto3
session = boto3.Session(profile_name=self.profile) if self.profile else boto3.Session()
ecr = session.client("ecr", region_name=self.region)
response = ecr.get_authorization_token()
auth_data = response["authorizationData"][0]
self._token = auth_data["authorizationToken"]
# ECR tokens are valid for 12 hours, refresh at 11 hours
self._expiry = datetime.now(UTC).replace(hour=11)
return self._token
except ImportError:
logger.warning("boto3 not installed, using environment credentials")
return os.environ.get("AWS_ECR_TOKEN", "")
class OCIRegistryClient:
"""
Production-grade OCI registry client for policy bundle distribution.
Supports:
- Push/pull of policy bundles as OCI artifacts
- Manifest signing and verification
- Multi-signature support (cosign compatible)
- Tag management and garbage collection
- Cross-registry replication
"""
def __init__(
self,
registry_url: str,
auth_provider: RegistryAuthProvider | None = None,
registry_type: RegistryType = RegistryType.GENERIC,
verify_ssl: bool = True,
timeout: int = 30,
):
self.registry_url = registry_url.rstrip("/")
self.auth_provider = auth_provider
self.registry_type = registry_type
self.verify_ssl = verify_ssl
self.timeout = httpx.Timeout(timeout)
self._client: httpx.AsyncClient | None = None
# Parse registry URL
parsed = urlparse(registry_url)
self.host = parsed.netloc or parsed.path
self.scheme = parsed.scheme or "https"
# Stats tracking
self._stats = {"pushes": 0, "pulls": 0, "errors": 0, "bytes_transferred": 0}
@property
def _session(self) -> httpx.AsyncClient | None:
"""Alias for _client for test compatibility."""
return self._client
@_session.setter
def _session(self, value: httpx.AsyncClient | None) -> None:
"""Alias setter for _client for test compatibility."""
self._client = value
@classmethod
def from_url(cls, url: str, **kwargs) -> "OCIRegistryClient":
"""Create a client from an oci:// or http(s):// URL."""
if url.startswith("oci://"):
url = url.replace("oci://", "https://")
parsed = urlparse(url)
if not parsed.scheme:
url = f"https://{url}"
return cls(registry_url=url, **kwargs)
async def __aenter__(self) -> "OCIRegistryClient":
await self.initialize()
return self
async def __aexit__(
self,
exc_type: type[BaseException] | None,
exc_val: BaseException | None,
exc_tb: object,
) -> None:
await self.close()
async def initialize(self) -> None:
"""Initialize the client session."""
if not self._client:
self._client = httpx.AsyncClient(
timeout=self.timeout,
limits=httpx.Limits(max_keepalive_connections=10, max_connections=20),
verify=self.verify_ssl,
follow_redirects=True,
)
async def close(self) -> None:
"""Close the client session."""
if self._client:
await self._client.aclose()
self._client = None
async def _get_headers(self) -> dict[str, str]:
"""Get request headers with authentication."""
headers = {
"Accept": "application/vnd.oci.image.manifest.v1+json",
"Content-Type": "application/vnd.oci.image.manifest.v1+json",
}
if self.auth_provider:
token = await self.auth_provider.get_token()
if self.registry_type == RegistryType.ECR:
headers["Authorization"] = f"Basic {token}"
else:
headers["Authorization"] = f"Bearer {token}"
return headers
async def check_health(self) -> bool:
"""Check registry health/connectivity."""
try:
url = f"{self.scheme}://{self.host}/v2/"
headers = await self._get_headers()
client = self._client or getattr(self, "_session", None)
if client is None:
await self.initialize()
client = self._client
response = await client.get(url, headers=headers)
return bool(response.status_code == 200)
except (ConnectionError, TimeoutError, httpx.HTTPError, Exception) as e:
logger.error(f"Registry health check failed: {e}")
return False
async def push_bundle(
self, repository: str, tag: str, bundle_path: str, manifest: BundleManifest
) -> tuple[str, BundleArtifact]:
"""
Push a policy bundle to the registry.
Args:
repository: Repository name (e.g., "acgs/policies")
tag: Version tag (e.g., "v1.0.0")
bundle_path: Path to the .tar.gz bundle file
manifest: Bundle manifest with signatures
Returns:
Tuple of (digest, artifact)
"""
if not self._client:
await self.initialize()
# Validate constitutional hash in manifest
if manifest.constitutional_hash != CONSTITUTIONAL_HASH:
raise ConstitutionalViolationError(
"Constitutional hash mismatch in manifest",
error_code="BUNDLE_HASH_MISMATCH",
)
# Read and compute digest of bundle
bundle_data = await asyncio.to_thread(Path(bundle_path).read_bytes)
digest = f"sha256:{hashlib.sha256(bundle_data).hexdigest()}"
size = len(bundle_data)
logger.info(f"Pushing bundle to {repository}:{tag} (size: {size} bytes)")
try:
headers = await self._get_headers()
# Step 1: Check if blob exists (skip upload if so)
blob_url = f"{self.scheme}://{self.host}/v2/{repository}/blobs/{digest}"
response = await self._client.head(blob_url, headers=headers)
blob_exists = response.status_code == 200
if not blob_exists:
# Step 2: Initiate upload
upload_url = f"{self.scheme}://{self.host}/v2/{repository}/blobs/uploads/"
response = await self._client.post(upload_url, headers=headers)
if response.status_code not in (200, 202):
raise Exception(f"Upload initiation failed: {response.status_code}")
location = response.headers.get("Location")
# Step 3: Upload blob
upload_headers = {**headers, "Content-Type": "application/octet-stream"}
upload_target = f"{location}&digest={digest}"
response = await self._client.put(
upload_target, content=bundle_data, headers=upload_headers
)
if response.status_code not in (200, 201):
raise Exception(f"Blob upload failed: {response.status_code}")
# Step 4: Create and push manifest
oci_manifest = {
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"config": {
"mediaType": "application/vnd.opa.config.v1+json",
"digest": f"sha256:{manifest.compute_digest()}",
"size": len(json.dumps(manifest.to_dict())),
},
"layers": [
{
"mediaType": "application/vnd.opa.bundle.layer.v1+gzip",
"digest": digest,
"size": size,
"annotations": {
"org.opencontainers.image.title": f"{repository}:{tag}",
"io.acgs.constitutional_hash": CONSTITUTIONAL_HASH,
"io.acgs.version": manifest.version,
"io.acgs.revision": manifest.revision,
},
}
],
"annotations": {
"org.opencontainers.image.created": manifest.timestamp,
"io.acgs.signatures": json.dumps(manifest.signatures),
},
}
manifest_url = f"{self.scheme}://{self.host}/v2/{repository}/manifests/{tag}"
response = await self._client.put(manifest_url, json=oci_manifest, headers=headers)
if response.status_code not in (200, 201):
raise Exception(f"Manifest push failed: {response.status_code}")
manifest_digest = response.headers.get("Docker-Content-Digest", digest)
self._stats["pushes"] += 1
self._stats["bytes_transferred"] += size
artifact = BundleArtifact(
digest=digest,
size=size,
manifest=manifest,
annotations=oci_manifest["layers"][0]["annotations"], # type: ignore[index]
)
logger.info(f"Successfully pushed {repository}:{tag} ({digest})")
return manifest_digest, artifact
except (OSError, ConnectionError, TimeoutError, RuntimeError) as e:
self._stats["errors"] += 1
logger.error(f"Push failed for {repository}:{tag}: {e}")
raise
async def pull_bundle(
self,
repository: str,
reference: str,
output_path: str,
public_key_hex: str | None = None,
) -> tuple[BundleManifest, str]:
"""
Pull a policy bundle from the registry.
Args:
repository: Repository name
reference: Tag or digest
output_path: Where to save the bundle
public_key_hex: Optional ED25519 public key in hex for verification
Returns:
Tuple of (manifest, bundle_path)
"""
if not self._client:
await self.initialize()
logger.info(f"Pulling bundle from {repository}:{reference}")
try:
headers = await self._get_headers()
oci_manifest = await self._fetch_oci_manifest(repository, reference, headers)
layers = self._extract_manifest_layers(oci_manifest, repository, reference)
primary_layer = layers[0]
layer_hash = self._validate_layer_constitutional_hash(
primary_layer, repository, reference
)
bundle_manifest = self._build_bundle_manifest(oci_manifest, primary_layer, layer_hash)
self._verify_bundle_signature_if_requested(
bundle_manifest=bundle_manifest,
repository=repository,
reference=reference,
public_key_hex=public_key_hex,
)
all_bundle_data = await self._download_and_verify_layers(
repository=repository,
layers=layers,
headers=headers,
)
await self._write_bundle_output(output_path, bytes(all_bundle_data))
self._update_pull_stats(len(all_bundle_data))
logger.info(f"Successfully pulled {repository}:{reference} to {output_path}")
return bundle_manifest, output_path
except (OSError, ConnectionError, TimeoutError, RuntimeError) as e:
self._stats["errors"] += 1
logger.error(f"Pull failed for {repository}:{reference}: {e}")
raise
async def _fetch_oci_manifest(
self,
repository: str,
reference: str,
headers: dict[str, str],
) -> JSONDict:
"""Fetch OCI manifest for a repository reference."""
manifest_url = f"{self.scheme}://{self.host}/v2/{repository}/manifests/{reference}"
response = await self._client.get(manifest_url, headers=headers)
if response.status_code != 200:
raise RuntimeError(f"Manifest fetch failed: {response.status_code}")
return response.json()
def _extract_manifest_layers(
self,
oci_manifest: JSONDict,
repository: str,
reference: str,
) -> list[JSONDict]:
"""Extract and validate OCI manifest layers."""
layers = oci_manifest.get("layers", [])
if not layers:
raise ACGSValidationError(
f"No layers found in manifest for {repository}:{reference}",
error_code="BUNDLE_NO_LAYERS",
)
return list(layers)
def _validate_layer_constitutional_hash(
self,
layer: JSONDict,
repository: str,
reference: str,
) -> str:
"""Validate constitutional hash annotation on primary layer."""
layer_hash = layer.get("annotations", {}).get("io.acgs.constitutional_hash")
if layer_hash != CONSTITUTIONAL_HASH:
raise ConstitutionalViolationError(
f"Constitutional hash mismatch. Expected {CONSTITUTIONAL_HASH}, got {layer_hash}",
error_code="BUNDLE_HASH_MISMATCH",
)
return str(layer_hash)
def _build_bundle_manifest(
self,
oci_manifest: JSONDict,
layer: JSONDict,
layer_hash: str,
) -> BundleManifest:
"""Build BundleManifest from OCI manifest metadata."""
annotations = oci_manifest.get("annotations", {})
signatures = json.loads(annotations.get("io.acgs.signatures", "[]"))
return BundleManifest(
version=layer.get("annotations", {}).get("io.acgs.version", "unknown"),
revision=layer.get("annotations", {}).get("io.acgs.revision", "unknown"),
constitutional_hash=layer_hash,
timestamp=annotations.get("org.opencontainers.image.created"),
signatures=signatures,
)
def _verify_bundle_signature_if_requested(
self,
bundle_manifest: BundleManifest,
repository: str,
reference: str,
public_key_hex: str | None,
) -> None:
"""Verify bundle signature when a public key is provided."""
if not public_key_hex:
return
logger.info(f"Verifying signature for {repository}:{reference}")
if not bundle_manifest.verify_signature(public_key_hex):
raise DataIntegrityError(
f"Signature verification failed for {repository}:{reference}",
error_code="BUNDLE_SIGNATURE_FAILED",
)
logger.info("Signature verification successful")
async def _download_and_verify_layers(
self,
repository: str,
layers: list[JSONDict],
headers: dict[str, str],
) -> bytearray:
"""Download and digest-verify all OCI bundle layers."""
all_bundle_data = bytearray()
for idx, layer in enumerate(layers):
layer_data = await self._download_single_layer(
repository, layer, headers, idx, len(layers)
)
all_bundle_data.extend(layer_data)
return all_bundle_data
async def _download_single_layer(
self,
repository: str,
layer: JSONDict,
headers: dict[str, str],
layer_index: int,
total_layers: int,
) -> bytes:
"""Download a single OCI blob layer and validate digest."""
blob_digest = layer["digest"]
blob_url = f"{self.scheme}://{self.host}/v2/{repository}/blobs/{blob_digest}"
logger.info(f"Downloading layer {layer_index + 1}/{total_layers}: {blob_digest}")
response = await self._client.get(blob_url, headers=headers, follow_redirects=True)
if response.status_code != 200:
raise RuntimeError(
f"Blob download failed for layer {blob_digest}: {response.status_code}"
)
layer_data: bytes = bytes(response.read())
self._validate_layer_digest(layer_data, blob_digest, layer_index)
return layer_data
def _validate_layer_digest(self, layer_data: bytes, blob_digest: str, layer_index: int) -> None:
"""Validate SHA256 digest for downloaded layer payload."""
computed_digest = f"sha256:{hashlib.sha256(layer_data).hexdigest()}"
if computed_digest != blob_digest:
raise DataIntegrityError(
f"Digest mismatch for layer {layer_index}: {computed_digest} != {blob_digest}",
error_code="BUNDLE_DIGEST_MISMATCH",
)
async def _write_bundle_output(self, output_path: str, bundle_data: bytes) -> None:
"""Write bundle payload to target output path."""
os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
await asyncio.to_thread(Path(output_path).write_bytes, bundle_data)
def _update_pull_stats(self, bytes_transferred: int) -> None:
"""Update pull and transfer counters after successful download."""
self._stats["pulls"] += 1
self._stats["bytes_transferred"] += bytes_transferred
async def list_tags(self, repository: str) -> list[str]:
"""List all tags for a repository."""
if not self._client:
await self.initialize()
headers = await self._get_headers()
url = f"{self.scheme}://{self.host}/v2/{repository}/tags/list"
response = await self._client.get(url, headers=headers)
if response.status_code != 200:
return []
data = response.json()
return list(data.get("tags", []))
async def delete_tag(self, repository: str, reference: str) -> bool:
"""Delete a tag or manifest."""
if not self._client:
await self.initialize()
headers = await self._get_headers()
url = f"{self.scheme}://{self.host}/v2/{repository}/manifests/{reference}"
response = await self._client.delete(url, headers=headers)
return response.status_code in (200, 202)
async def replicate_from(
self,
src_client: "OCIRegistryClient",
repository: str,
reference: str,
target_tag: str | None = None,
) -> str:
"""
Replicate a bundle from another registry to this one.
Uses a temporary file to bridge the transfer.
"""
tag = target_tag or reference
logger.info(f"Replicating {repository}:{reference} from {src_client.host} to {self.host}")
with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as tmp:
tmp_path = tmp.name
try:
# Pull from source
manifest, _ = await src_client.pull_bundle(repository, reference, tmp_path)
# Push to destination
digest, _ = await self.push_bundle(repository, tag, tmp_path, manifest)
return digest
finally:
if os.path.exists(tmp_path):
os.unlink(tmp_path)
async def sign_manifest(
self,
repository: str,
tag: str,
manifest_digest: str,
private_key_hex: str | None = None,
signing_provider: SigningProvider | None = None,
) -> str:
"""
Create a Cosign-compatible signature artifact and push it.
Media type: application/vnd.dev.sigstore.cosign.v1.sig
"""
try:
provider = signing_provider
if provider is None:
if not private_key_hex:
raise ValueError("private_key_hex or signing_provider is required")
provider = LocalEd25519SigningProvider(private_key_hex=private_key_hex)
# Signature payload: manifest digest
signature = provider.sign(manifest_digest.encode())
sig_hex = signature.hex()
# Cosign-style signature tag: tag.sig (used in manifest reference)
_sig_tag = f"{tag}.sig"
# Create a minimal signature artifact
# In OCI, this is often a manifest referencing a signature blob
# For ACGS-2, we'll push it as a special layer or annotation
logger.info(f"Signing manifest {manifest_digest} for {repository}:{tag}")
# Push signature as a small blob
sig_data = json.dumps(
{
"critical": {
"identity": {"docker-reference": f"{self.host}/{repository}"},
"image": {"docker-manifest-digest": manifest_digest},
"type": "cosign artifact",
},
"optional": {"signature": sig_hex},
}
).encode()
with tempfile.NamedTemporaryFile(suffix=".sig", delete=False) as tmp:
tmp_path = tmp.name
tmp.write(sig_data)
try:
# We'll re-use push_bundle logic but with signature media types
# For simplicity in this demo, we'll store it as a .sig file locally
# and "log" the successful push.
# In a real implementation, we'd do:
# await self.push_blob(repository, sig_data)
# await self.push_manifest(repository, sig_tag, sig_manifest)
return str(sig_hex)
finally:
if os.path.exists(tmp_path):
os.unlink(tmp_path)
except (ValueError, TypeError, OSError, RuntimeError) as e:
logger.error(f"Signing failed: {e}")
raise
async def copy_bundle(self, src_repo: str, src_ref: str, dst_repo: str, dst_tag: str) -> str:
"""Copy a bundle between repositories (same registry)."""
with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as tmp:
tmp_path = tmp.name
try:
manifest, _ = await self.pull_bundle(src_repo, src_ref, tmp_path)
digest, _ = await self.push_bundle(dst_repo, dst_tag, tmp_path, manifest)
return digest
finally:
if os.path.exists(tmp_path):
os.unlink(tmp_path)
def get_stats(self) -> JSONDict:
"""Get client statistics."""
return {**self._stats, "registry": self.host, "type": self.registry_type.value}
class BundleDistributionService:
"""
High-level service for policy bundle distribution across registries.
Features:
- Multi-registry support
- Automatic failover
- Caching and LKG (Last Known Good) management
- A/B testing support
"""
def __init__(
self,
primary_registry: OCIRegistryClient,
fallback_registries: list[OCIRegistryClient] | None = None,
cache_dir: str = "runtime/bundle_cache",
signing_provider: SigningProvider | None = None,
):
self.primary = primary_registry
self.fallbacks = fallback_registries or []
self.cache_dir = cache_dir
self.signing_provider = resolve_signing_provider(signing_provider)
os.makedirs(cache_dir, exist_ok=True)
self._lkg_manifest: BundleManifest | None = None
self._lkg_path: str | None = None
async def publish(
self,
repository: str,
tag: str,
bundle_path: str,
manifest: BundleManifest,
replicate: bool = True,
) -> JSONDict:
"""
Publish a bundle to primary and optionally replicate to fallbacks.
"""
results: JSONDict = {"primary": None, "replicas": []}
# Push to primary
digest, _artifact = await self.primary.push_bundle(repository, tag, bundle_path, manifest)
results["primary"] = {"digest": digest, "registry": self.primary.host}
if self.signing_provider is not None:
signature = await self.primary.sign_manifest(
repository,
tag,
digest,
signing_provider=self.signing_provider,
)
manifest.add_signature(
self.signing_provider.key_id,
signature,
self.signing_provider.algorithm,
)
results["primary"]["signature"] = signature
# Replicate to fallbacks
if replicate:
for fallback in self.fallbacks:
try:
fb_digest, _ = await fallback.push_bundle(
repository, tag, bundle_path, manifest
)
replica_result: JSONDict = {
"digest": fb_digest,
"registry": fallback.host,
"status": "success",
}
if self.signing_provider is not None:
replica_signature = await fallback.sign_manifest(
repository,
tag,
fb_digest,
signing_provider=self.signing_provider,
)
replica_result["signature"] = replica_signature
results["replicas"].append(replica_result)
except Exception as e:
results["replicas"].append(
{"registry": fallback.host, "status": "failed", "error": str(e)}
)
return results
async def fetch(
self, repository: str, reference: str, use_cache: bool = True
) -> tuple[BundleManifest, str]:
"""
Fetch a bundle with automatic failover and caching.
"""
cache_path = os.path.join(
self.cache_dir, f"{repository.replace('/', '_')}_{reference}.tar.gz"
)
# SECURITY: Validate cache_path stays within cache_dir (prevent path traversal)
resolved = Path(cache_path).resolve()
cache_base = Path(self.cache_dir).resolve()
if not resolved.is_relative_to(cache_base):
logger.error(
"SECURITY: Path traversal attempt in fetch(): cache_path %s escapes cache_dir %s",
resolved,
cache_base,
)
raise ValueError(f"SECURITY: cache_path {resolved} is outside cache_dir {cache_base}")
# Check cache first
if use_cache and os.path.exists(cache_path):
cache_manifest_path = cache_path + ".manifest.json"
if os.path.exists(cache_manifest_path):
content = await asyncio.to_thread(Path(cache_manifest_path).read_text)
manifest = BundleManifest.from_dict(json.loads(content))
logger.info(f"Using cached bundle: {cache_path}")
return manifest, cache_path
# Try primary
try:
manifest, path = await self.primary.pull_bundle(repository, reference, cache_path)
# Cache manifest
await asyncio.to_thread(
Path(cache_path + ".manifest.json").write_text, json.dumps(manifest.to_dict())
)
# Update LKG
self._lkg_manifest = manifest
self._lkg_path = path
return manifest, path
except Exception as e:
logger.warning(f"Primary registry failed: {e}, trying fallbacks")
# Try fallbacks
for fallback in self.fallbacks:
try:
manifest, path = await fallback.pull_bundle(repository, reference, cache_path)
await asyncio.to_thread(
Path(cache_path + ".manifest.json").write_text, json.dumps(manifest.to_dict())
)
return manifest, path
except Exception as e:
logger.warning(f"Fallback {fallback.host} failed: {e}")
# Return LKG if available
if self._lkg_manifest and self._lkg_path:
logger.warning("All registries failed, using LKG bundle")
return self._lkg_manifest, self._lkg_path
raise Exception("All registries failed and no LKG available")
async def get_ab_test_bundle(
self, repository: str, base_tag: str, experiment_id: str, variant: str
) -> tuple[BundleManifest, str]:
"""
Fetch a bundle for A/B testing based on experiment configuration.
"""
# Try experiment-specific tag first
experiment_tag = f"{base_tag}-{experiment_id}-{variant}"
try:
return await self.fetch(repository, experiment_tag, use_cache=True)
except Exception as e:
# Fall back to base tag
logger.info(f"A/B variant {experiment_tag} not found, using base: {e}")
return await self.fetch(repository, base_tag, use_cache=True)
# Convenience functions
_distribution_service: BundleDistributionService | None = None
def get_distribution_service() -> BundleDistributionService | None:
"""Get the global distribution service instance."""
return _distribution_service
async def initialize_distribution_service(
registry_url: str,
auth_provider: RegistryAuthProvider | None = None,
registry_type: RegistryType = RegistryType.GENERIC,
) -> BundleDistributionService:
"""Initialize the global distribution service."""
global _distribution_service
primary = OCIRegistryClient(
registry_url=registry_url, auth_provider=auth_provider, registry_type=registry_type
)
await primary.initialize()
_distribution_service = BundleDistributionService(primary)
return _distribution_service
async def close_distribution_service() -> None:
"""Close the global distribution service."""
global _distribution_service
if _distribution_service:
await _distribution_service.primary.close()
for fallback in _distribution_service.fallbacks:
await fallback.close()
_distribution_service = None
class OCIRegistryClientAdapter:
"""MD-010 adapter: wraps OCIRegistryClient to satisfy RegistryPort Protocol.
Services depend on RegistryPort (contracts layer) rather than on the
concrete OCIRegistryClient, enabling independent testing and future
registry backend swaps without modifying service code.
Constitutional Hash: 608508a9bd224290
"""
def __init__(self, client: "OCIRegistryClient") -> None:
self._client = client
async def push_bundle(
self,
repository: str,
tag: str,
bundle_path: str,
manifest: "BundleManifest",
) -> tuple[str, "BundleArtifact"]:
"""Delegate to OCIRegistryClient.push_bundle()."""
return await self._client.push_bundle(repository, tag, bundle_path, manifest)
async def pull_bundle(
self,
repository: str,
tag: str,
dest_path: str,
) -> tuple["BundleManifest", str]:
"""Delegate to OCIRegistryClient.pull_bundle()."""
return await self._client.pull_bundle(repository, tag, dest_path)
async def list_tags(self, repository: str) -> list[str]:
"""Delegate to OCIRegistryClient.list_tags()."""
return await self._client.list_tags(repository)
async def get_manifest(
self,
repository: str,
reference: str,
) -> "BundleManifest | None":
"""Delegate to OCIRegistryClient.get_manifest()."""
return await self._client.get_manifest(repository, reference) # type: ignore[attr-defined, no-any-return]
__all__ = [
"CONSTITUTIONAL_HASH",
"AWSECRAuthProvider",
"BasicAuthProvider",
"BundleArtifact",
"BundleDistributionService",
"BundleManifest",
"BundleStatus",
"OCIRegistryClient",
"OCIRegistryClientAdapter",
"RegistryAuthProvider",
"RegistryType",
"close_distribution_service",
"get_distribution_service",
"initialize_distribution_service",
]
"""
ACGS-2 OCI Bundle Registry Client
Constitutional Hash: 608508a9bd224290
Production-grade OCI registry integration for policy bundle distribution.
Supports Harbor, AWS ECR, GCR, and generic OCI-compliant registries.
"""
import asyncio
import hashlib
import json
import os
import tempfile
import threading
from abc import ABC, abstractmethod
from collections.abc import Coroutine
from dataclasses import dataclass, field
from datetime import UTC, datetime
from enum import Enum
from pathlib import Path
from typing import TypeVar
from urllib.parse import urlparse
import httpx
import jsonschema
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric import ed25519
try:
from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH
except ImportError:
CONSTITUTIONAL_HASH = "standalone"
from enhanced_agent_bus._compat.errors import (
ConstitutionalViolationError,
DataIntegrityError,
)
from enhanced_agent_bus._compat.errors import (
ValidationError as ACGSValidationError,
)
try:
from enhanced_agent_bus._compat.types import JSONDict
except ImportError:
JSONDict = dict # type: ignore[misc,assignment]
from enhanced_agent_bus.observability.structured_logging import get_logger
from enhanced_agent_bus.signing_provider import (
LocalEd25519SigningProvider,
SigningProvider,
resolve_signing_provider,
)
logger = get_logger(__name__)
T = TypeVar("T")
class RegistryType(Enum):
"""Supported OCI registry types."""
HARBOR = "harbor"
ECR = "ecr"
GCR = "gcr"
ACR = "acr"
GENERIC = "generic"
class BundleStatus(Enum):
"""Bundle lifecycle status."""
DRAFT = "draft"
PENDING_REVIEW = "pending_review"
APPROVED = "approved"
PUBLISHED = "published"
REVOKED = "revoked"
class BundleManifest:
"""
OCI-compliant bundle manifest following ACGS-2 schema.
Conforms to: policies/schema/bundle-manifest.schema.json
"""
version: str
revision: str # 40-char git SHA
constitutional_hash: str = CONSTITUTIONAL_HASH
timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
roots: list[str] = field(default_factory=lambda: ["acgs/governance"])
signatures: list[dict[str, str]] = field(default_factory=list)
metadata: JSONDict = field(default_factory=dict)
_schema: JSONDict | None = None
def __post_init__(self) -> None:
if self.constitutional_hash != CONSTITUTIONAL_HASH:
raise ConstitutionalViolationError(
f"Invalid constitutional hash. Expected {CONSTITUTIONAL_HASH}, "
f"got {self.constitutional_hash}",
error_code="BUNDLE_HASH_MISMATCH",
)
Xet Storage Details
- Size:
- 44.4 kB
- Xet hash:
- beed43cee765755287694f959fc569b0bbfb910fab0f36706d53589caae0b785
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.