apsimo 1.3.0__py3-none-any.whl

apsimo/chain/transactions.py

@@ -0,0 +1,250 @@
+"""Transaction types and chain state dataclasses for ColonyChain.
+
+Each transaction type is fully typed. The ChainState dataclass holds the
+complete materialized state derived from replaying all committed blocks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Callable
+
+
+# ---------------------------------------------------------------------------
+# Transaction type enum
+# ---------------------------------------------------------------------------
+
+class TxType(str, Enum):
+    COLONY_REGISTER = "colony_register"
+    COLONY_ROTATE_KEY = "colony_rotate_key"
+    COLONY_REVOKE_KEY = "colony_revoke_key"
+    COLONY_RELEASE_NAME = "colony_release_name"
+    TRUST_ATTEST = "trust_attest"
+    UNTRUST_ATTEST = "untrust_attest"
+    SENTINEL_REGISTER = "sentinel_register"
+    SENTINEL_DEREGISTER = "sentinel_deregister"
+    COLONY_SUSPEND = "colony_suspend"
+    COLONY_REINSTATE = "colony_reinstate"
+    PROTOCOL_UPGRADE = "protocol_upgrade"
+
+    # Plugin security extensions
+    PLUGIN_PUBLISH = "plugin_publish"
+    PLUGIN_ATTESTATION = "plugin_attestation"
+    PLUGIN_FLAG = "plugin_flag"
+    PLUGIN_QUARANTINE = "plugin_quarantine"  # system-generated only
+
+
+# ---------------------------------------------------------------------------
+# Transaction
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Transaction:
+    """A single chain transaction with Ed25519 signature."""
+
+    tx_id: str
+    type: TxType
+    from_colony_id: str
+    timestamp: str
+    nonce: int
+    payload: dict[str, Any]
+    signature: str  # Ed25519 hex
+
+    @classmethod
+    def create(
+        cls,
+        tx_type: TxType,
+        from_colony_id: str,
+        nonce: int,
+        payload: dict[str, Any],
+        sign_fn: Callable[[bytes], str],
+    ) -> "Transaction":
+        """Create and sign a transaction."""
+        tx_id = str(uuid.uuid4())
+        ts = datetime.now(timezone.utc).isoformat()
+        signing_payload = {
+            "tx_id": tx_id,
+            "type": tx_type.value,
+            "from_colony_id": from_colony_id,
+            "timestamp": ts,
+            "nonce": nonce,
+            "payload": payload,
+        }
+        canonical = json.dumps(signing_payload, sort_keys=True, separators=(",", ":"))
+        sig = sign_fn(canonical.encode())
+        return cls(
+            tx_id=tx_id,
+            type=tx_type,
+            from_colony_id=from_colony_id,
+            timestamp=ts,
+            nonce=nonce,
+            payload=payload,
+            signature=sig,
+        )
+
+    def signing_bytes(self) -> bytes:
+        """Return the canonical bytes that were/should be signed."""
+        payload = {
+            "tx_id": self.tx_id,
+            "type": self.type.value if isinstance(self.type, TxType) else self.type,
+            "from_colony_id": self.from_colony_id,
+            "timestamp": self.timestamp,
+            "nonce": self.nonce,
+            "payload": self.payload,
+        }
+        return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tx_id": self.tx_id,
+            "type": self.type.value if isinstance(self.type, TxType) else self.type,
+            "from_colony_id": self.from_colony_id,
+            "timestamp": self.timestamp,
+            "nonce": self.nonce,
+            "payload": self.payload,
+            "signature": self.signature,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Transaction":
+        try:
+            tx_type: Any = TxType(d["type"])
+        except (ValueError, KeyError):
+            tx_type = d.get("type", "unknown")
+        return cls(
+            tx_id=d["tx_id"],
+            type=tx_type,
+            from_colony_id=d["from_colony_id"],
+            timestamp=d["timestamp"],
+            nonce=d["nonce"],
+            payload=d["payload"],
+            signature=d.get("signature", ""),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Chain state dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class KeyHistoryEntry:
+    public_key_hex: str
+    active_from_height: int
+    rotated_at_height: int | None = None   # None = still active
+    revoked_at_height: int | None = None   # None = not revoked
+    revocation_tx: str | None = None
+
+
+@dataclass
+class ColonyRecord:
+    colony_id: str
+    name: str
+    active_public_key_hex: str
+    endpoint: str
+    description: str
+    capabilities: list[str]
+    protocol_version: str
+    registered_at_height: int
+    registered_at_tx: str
+    is_genesis_admin: bool
+    status: str  # "active" | "suspended" | "deregistered"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TrustEdge:
+    from_colony_id: str
+    to_colony_id: str
+    trust_level: int  # 0-4
+    attested_at_height: int
+    attested_at_tx: str
+    valid_until: str | None = None  # ISO-8601 or None
+
+
+@dataclass
+class UntrustEvent:
+    from_colony_id: str
+    target_colony_id: str
+    at_height: int
+    tx_id: str
+    report_abuse: bool
+    timestamp: str
+
+
+@dataclass
+class SentinelRecord:
+    sentinel_id: str
+    colony_id: str
+    host: str
+    port: int
+    public_key_hex: str
+    registered_at_height: int
+    status: str  # "active" | "demoted" | "deregistered"
+    uptime_percent: float
+
+
+@dataclass
+class ProtocolConfig:
+    block_interval_secs: int = 30
+    untrust_threshold: int = 3
+    untrust_window_days: int = 30
+    uptime_requirement_percent: float = 99.0
+    min_sentinels: int = 1
+    min_protocol_version: str = "1.0.0"
+
+
+@dataclass
+class ProtocolUpgradeRecord:
+    upgrade_id: str
+    title: str
+    proposed_at_height: int
+    activation_height: int
+    ratified: bool
+    changes: dict[str, Any]
+
+
+@dataclass
+class ChainState:
+    """Complete materialized state of the chain at a given height."""
+
+    height: int = 0
+    last_block_hash: str = "0" * 64
+    colony_registry: dict[str, ColonyRecord] = field(default_factory=dict)
+    name_registry: dict[str, str] = field(default_factory=dict)  # name -> colony_id
+    key_history: dict[str, list[KeyHistoryEntry]] = field(default_factory=dict)
+    trust_graph: dict[tuple[str, str], TrustEdge] = field(default_factory=dict)
+    untrust_counters: dict[str, list[UntrustEvent]] = field(default_factory=dict)
+    sentinel_roster: dict[str, SentinelRecord] = field(default_factory=dict)
+    suspended_colonies: set[str] = field(default_factory=set)
+    protocol_config: ProtocolConfig = field(default_factory=ProtocolConfig)
+    upgrade_history: list[ProtocolUpgradeRecord] = field(default_factory=list)
+    genesis_admin_id: str = ""
+    network_id: str = ""
+    # Plugin security registry
+    plugin_registry: dict[str, Any] = field(default_factory=dict)  # plugin_hash -> PluginChainRecord
+    # Track publish counts per colony for rate limiting
+    plugin_publish_counts: dict[str, list[str]] = field(default_factory=dict)  # colony_id -> list of timestamps
+
+    def colony_id_for_name(self, name: str) -> str | None:
+        return self.name_registry.get(name.lower())
+
+    def active_key_for_colony(self, colony_id: str) -> str | None:
+        record = self.colony_registry.get(colony_id)
+        if record:
+            return record.active_public_key_hex
+        return None
+
+    def is_active(self, colony_id: str) -> bool:
+        record = self.colony_registry.get(colony_id)
+        return record is not None and record.status == "active"
+
+    def is_suspended(self, colony_id: str) -> bool:
+        return colony_id in self.suspended_colonies
+
+    def active_sentinels(self) -> list[SentinelRecord]:
+        return [s for s in self.sentinel_roster.values() if s.status == "active"]

apsimo/chain/validation.py

@@ -0,0 +1,397 @@
+"""Chain validation: block integrity, transaction signatures, state transitions.
+
+All validation is deterministic — same state + same input = same result.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+from cryptography.exceptions import InvalidSignature
+
+from .block import Block, build_merkle_root
+from .transactions import (
+    ChainState,
+    TxType,
+    Transaction,
+)
+
+logger = logging.getLogger(__name__)
+
+_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9\-]{0,62}[a-z0-9]?$")
+
+
+@dataclass
+class ValidationResult:
+    ok: bool
+    reason: str = ""
+
+    @property
+    def valid(self) -> bool:
+        """Alias for ok — used by nonce validator tests and external callers."""
+        return self.ok
+
+    @classmethod
+    def success(cls) -> "ValidationResult":
+        return cls(ok=True)
+
+    @classmethod
+    def fail(cls, reason: str) -> "ValidationResult":
+        return cls(ok=False, reason=reason)
+
+
+def _verify_ed25519(public_key_hex: str, data: bytes, signature_hex: str) -> bool:
+    """Verify an Ed25519 signature. Returns False on any error."""
+    try:
+        pub_bytes = bytes.fromhex(public_key_hex)
+        sig_bytes = bytes.fromhex(signature_hex)
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+        pub_key = Ed25519PublicKey.from_public_bytes(pub_bytes)
+        pub_key.verify(sig_bytes, data)
+        return True
+    except (InvalidSignature, ValueError, Exception):
+        return False
+
+
+class TransactionValidator:
+    """Validates transactions against current chain state."""
+
+    def __init__(self, state: ChainState = None, chain_store=None) -> None:
+        self.state = state
+        self._chain_store = chain_store
+
+    def validate(self, tx: Transaction) -> ValidationResult:
+        """Full validation: signature, nonce, type-specific preconditions."""
+        # Basic structure
+        if not tx.tx_id:
+            return ValidationResult.fail("missing tx_id")
+        if not tx.from_colony_id:
+            return ValidationResult.fail("missing from_colony_id")
+
+        # System transactions (auto-generated) skip signature check
+        is_system = tx.from_colony_id == "system"
+
+        if not is_system:
+            nonce_result = self._check_nonce(tx)
+            if not nonce_result.ok:
+                return nonce_result
+
+            sig_result = self._verify_signature(tx)
+            if not sig_result.ok:
+                return sig_result
+
+        # Type-specific validation
+        return self._validate_by_type(tx)
+
+    def _verify_signature(self, tx: Transaction) -> ValidationResult:
+        """Verify Ed25519 signature against the colony's active key."""
+        colony = self.state.colony_registry.get(tx.from_colony_id)
+
+        # For colony_register, use the public key from the payload itself
+        if tx.type == TxType.COLONY_REGISTER:
+            pub_key_hex = tx.payload.get("public_key_hex", "")
+        elif colony is not None:
+            pub_key_hex = colony.active_public_key_hex
+        else:
+            return ValidationResult.fail(
+                f"colony {tx.from_colony_id!r} not registered"
+            )
+
+        if not pub_key_hex:
+            return ValidationResult.fail("no public key for colony")
+
+        data = tx.signing_bytes()
+        if not _verify_ed25519(pub_key_hex, data, tx.signature):
+            return ValidationResult.fail("invalid signature")
+        return ValidationResult.success()
+
+    def _check_nonce(self, tx: Transaction) -> ValidationResult:
+        """Verify nonce is strictly greater than colony's last accepted nonce.
+
+        The authoritative nonce check is enforced by ChainManager.submit_transaction()
+        via ChainStore.get_nonce() + DB UNIQUE(colony_id, nonce). This method is a
+        defence-in-depth layer for callers that use TransactionValidator directly
+        (e.g. federation sync, offline verification tools).
+
+        Fails closed when no ChainStore is injected: a missing store means replay
+        protection cannot be enforced, and validating without it would let
+        offline/federation callers accept replayed transactions.
+        """
+        if tx.type == TxType.COLONY_REGISTER:
+            # Genesis registrations have no prior nonce to compare against.
+            return ValidationResult.success()
+
+        if self._chain_store is None:
+            return ValidationResult.fail(
+                "TransactionValidator: chain_store not injected; cannot verify "
+                "nonce replay protection. Inject chain_store= when constructing "
+                "the validator."
+            )
+
+        last_nonce = self._chain_store.get_nonce(tx.from_colony_id)
+        if tx.nonce <= last_nonce:
+            return ValidationResult.fail(
+                f"Nonce replay: tx.nonce={tx.nonce} <= last_accepted={last_nonce}"
+            )
+        return ValidationResult.success()
+
+    def _validate_by_type(self, tx: Transaction) -> ValidationResult:
+        dispatch = {
+            TxType.COLONY_REGISTER: self._validate_colony_register,
+            TxType.COLONY_ROTATE_KEY: self._validate_colony_rotate_key,
+            TxType.COLONY_REVOKE_KEY: self._validate_colony_revoke_key,
+            TxType.COLONY_RELEASE_NAME: self._validate_colony_release_name,
+            TxType.TRUST_ATTEST: self._validate_trust_attest,
+            TxType.UNTRUST_ATTEST: self._validate_untrust_attest,
+            TxType.SENTINEL_REGISTER: self._validate_sentinel_register,
+            TxType.SENTINEL_DEREGISTER: self._validate_sentinel_deregister,
+            TxType.COLONY_SUSPEND: self._validate_colony_suspend,
+            TxType.COLONY_REINSTATE: self._validate_colony_reinstate,
+            TxType.PROTOCOL_UPGRADE: self._validate_protocol_upgrade,
+        }
+        handler = dispatch.get(tx.type)
+        if handler is None:
+            return ValidationResult.fail(f"unknown transaction type: {tx.type}")
+        return handler(tx)
+
+    def _validate_colony_register(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        name = p.get("name", "").lower()
+        colony_id = p.get("colony_id", "")
+        public_key_hex = p.get("public_key_hex", "")
+
+        if not name:
+            return ValidationResult.fail("colony_register: missing name")
+        if not _NAME_PATTERN.match(name):
+            return ValidationResult.fail(
+                f"colony_register: name {name!r} does not match required pattern"
+            )
+        if name in self.state.name_registry:
+            return ValidationResult.fail(
+                f"colony_register: name {name!r} already registered"
+            )
+        if colony_id in self.state.colony_registry:
+            return ValidationResult.fail(
+                f"colony_register: colony_id {colony_id!r} already registered"
+            )
+        # Verify colony_id = sha256(pubkey)
+        try:
+            expected_id = hashlib.sha256(bytes.fromhex(public_key_hex)).hexdigest()
+        except ValueError:
+            return ValidationResult.fail("colony_register: invalid public_key_hex")
+        if expected_id != colony_id:
+            return ValidationResult.fail(
+                "colony_register: colony_id does not match sha256(public_key)"
+            )
+        # Genesis admin can only appear once (in genesis block)
+        if p.get("genesis_admin", False) and self.state.genesis_admin_id:
+            return ValidationResult.fail(
+                "colony_register: genesis_admin=true only allowed in genesis block"
+            )
+        return ValidationResult.success()
+
+    def _validate_colony_rotate_key(self, tx: Transaction) -> ValidationResult:
+        colony = self.state.colony_registry.get(tx.from_colony_id)
+        if colony is None:
+            return ValidationResult.fail("colony_rotate_key: colony not registered")
+        if colony.status == "suspended":
+            return ValidationResult.fail("colony_rotate_key: colony is suspended")
+        p = tx.payload
+        new_key = p.get("new_public_key_hex", "")
+        if not new_key:
+            return ValidationResult.fail("colony_rotate_key: missing new_public_key_hex")
+        # New key must not be registered to another colony
+        for cid, record in self.state.colony_registry.items():
+            if cid != tx.from_colony_id and record.active_public_key_hex == new_key:
+                return ValidationResult.fail(
+                    "colony_rotate_key: new key already registered to another colony"
+                )
+        return ValidationResult.success()
+
+    def _validate_colony_revoke_key(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        revoked_key = p.get("revoked_key_hex", "")
+        if not revoked_key:
+            return ValidationResult.fail("colony_revoke_key: missing revoked_key_hex")
+        # Key must be in history of the target colony
+        # from_colony_id is either the colony itself, or "system"/"genesis"
+        target_id = tx.from_colony_id
+        history = self.state.key_history.get(target_id, [])
+        if not any(e.public_key_hex == revoked_key for e in history):
+            return ValidationResult.fail(
+                "colony_revoke_key: key not found in colony key history"
+            )
+        return ValidationResult.success()
+
+    def _validate_colony_release_name(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        name = p.get("name", "").lower()
+        owner_id = self.state.name_registry.get(name)
+        if owner_id is None:
+            return ValidationResult.fail(
+                f"colony_release_name: name {name!r} not registered"
+            )
+        is_genesis = tx.from_colony_id == self.state.genesis_admin_id
+        if owner_id != tx.from_colony_id and not is_genesis:
+            return ValidationResult.fail(
+                "colony_release_name: not authorized (not owner or genesis admin)"
+            )
+        return ValidationResult.success()
+
+    def _validate_trust_attest(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        target_id = p.get("target_colony_id", "")
+        if not self.state.is_active(tx.from_colony_id):
+            return ValidationResult.fail("trust_attest: attesting colony not active")
+        if not self.state.is_active(target_id):
+            return ValidationResult.fail("trust_attest: target colony not active")
+        trust_level = p.get("trust_level", -1)
+        if trust_level not in range(5):
+            return ValidationResult.fail("trust_attest: trust_level must be 0-4")
+        return ValidationResult.success()
+
+    def _validate_untrust_attest(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        target_id = p.get("target_colony_id", "")
+        if not self.state.colony_registry.get(tx.from_colony_id):
+            return ValidationResult.fail("untrust_attest: attesting colony not registered")
+        if not self.state.colony_registry.get(target_id):
+            return ValidationResult.fail("untrust_attest: target colony not registered")
+        return ValidationResult.success()
+
+    def _validate_sentinel_register(self, tx: Transaction) -> ValidationResult:
+        colony = self.state.colony_registry.get(tx.from_colony_id)
+        if colony is None:
+            return ValidationResult.fail("sentinel_register: colony not registered")
+        if colony.status == "suspended":
+            return ValidationResult.fail("sentinel_register: colony is suspended")
+        p = tx.payload
+        sentinel_id = p.get("sentinel_id", "")
+        if not sentinel_id:
+            return ValidationResult.fail("sentinel_register: missing sentinel_id")
+        if sentinel_id in self.state.sentinel_roster:
+            return ValidationResult.fail(
+                f"sentinel_register: sentinel_id {sentinel_id!r} already registered"
+            )
+        return ValidationResult.success()
+
+    def _validate_sentinel_deregister(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        sentinel_id = p.get("sentinel_id", "")
+        record = self.state.sentinel_roster.get(sentinel_id)
+        if record is None:
+            return ValidationResult.fail(
+                f"sentinel_deregister: sentinel {sentinel_id!r} not in roster"
+            )
+        is_genesis = tx.from_colony_id == self.state.genesis_admin_id
+        is_system = tx.from_colony_id == "system"
+        if record.colony_id != tx.from_colony_id and not is_genesis and not is_system:
+            return ValidationResult.fail(
+                "sentinel_deregister: not authorized (not owner or genesis admin)"
+            )
+        return ValidationResult.success()
+
+    def _validate_colony_suspend(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        target_id = p.get("target_colony_id", "")
+        if not target_id:
+            return ValidationResult.fail("colony_suspend: missing target_colony_id")
+        if target_id not in self.state.colony_registry:
+            return ValidationResult.fail("colony_suspend: target colony not registered")
+        if self.state.is_suspended(target_id):
+            return ValidationResult.fail("colony_suspend: colony already suspended")
+        is_genesis = tx.from_colony_id == self.state.genesis_admin_id
+        is_system = tx.from_colony_id == "system"
+        if not is_genesis and not is_system:
+            return ValidationResult.fail(
+                "colony_suspend: only genesis admin or system may suspend"
+            )
+        return ValidationResult.success()
+
+    def _validate_colony_reinstate(self, tx: Transaction) -> ValidationResult:
+        p = tx.payload
+        target_id = p.get("target_colony_id", "")
+        if not target_id:
+            return ValidationResult.fail("colony_reinstate: missing target_colony_id")
+        if not self.state.is_suspended(target_id):
+            return ValidationResult.fail("colony_reinstate: colony is not suspended")
+        is_genesis = tx.from_colony_id == self.state.genesis_admin_id
+        is_system = tx.from_colony_id == "system"
+        if not is_genesis and not is_system:
+            return ValidationResult.fail(
+                "colony_reinstate: only genesis admin or system may reinstate"
+            )
+        return ValidationResult.success()
+
+    def _validate_protocol_upgrade(self, tx: Transaction) -> ValidationResult:
+        is_genesis = tx.from_colony_id == self.state.genesis_admin_id
+        if not is_genesis:
+            return ValidationResult.fail(
+                "protocol_upgrade: only genesis admin may propose upgrades"
+            )
+        p = tx.payload
+        if not p.get("upgrade_id"):
+            return ValidationResult.fail("protocol_upgrade: missing upgrade_id")
+        if not p.get("title"):
+            return ValidationResult.fail("protocol_upgrade: missing title")
+        activation_height = p.get("activation_height", 0)
+        if activation_height <= self.state.height:
+            return ValidationResult.fail(
+                "protocol_upgrade: activation_height must be in the future"
+            )
+        return ValidationResult.success()
+
+
+class BlockValidator:
+    """Validates block structure, hash chain integrity, and merkle root."""
+
+    def validate_block(
+        self, block: Block, previous_block: Block | None
+    ) -> ValidationResult:
+        # Hash chain
+        if previous_block is None:
+            if block.index != 0:
+                return ValidationResult.fail("first block must have index 0")
+            if block.previous_hash != "0" * 64:
+                return ValidationResult.fail(
+                    "genesis block previous_hash must be 64 zeros"
+                )
+        else:
+            if block.index != previous_block.index + 1:
+                return ValidationResult.fail(
+                    f"expected index {previous_block.index + 1}, got {block.index}"
+                )
+            if block.previous_hash != previous_block.block_hash:
+                return ValidationResult.fail("previous_hash mismatch")
+
+        # Merkle root
+        tx_ids = [tx.tx_id for tx in block.transactions]
+        expected_merkle = build_merkle_root(tx_ids)
+        if block.merkle_root != expected_merkle:
+            return ValidationResult.fail(
+                f"merkle_root mismatch: {block.merkle_root!r} != {expected_merkle!r}"
+            )
+
+        return ValidationResult.success()
+
+    def validate_sentinel_signature(
+        self,
+        block: Block,
+        sentinel_public_key_hex: str,
+    ) -> ValidationResult:
+        """Verify the block's Ed25519 signature from the producing Sentinel."""
+        block_dict = block.to_dict()
+        block_dict.pop("signature", None)
+        canonical = json.dumps(block_dict, sort_keys=True, separators=(",", ":"))
+        data = canonical.encode()
+        if not _verify_ed25519(sentinel_public_key_hex, data, block.signature):
+            return ValidationResult.fail("block signature invalid")
+        return ValidationResult.success()

apsimo/channels/__init__.py

@@ -0,0 +1 @@
+"""Channel registration subsystem."""

apsimo/channels/manifest.py

@@ -0,0 +1,31 @@
+"""Channel manifest -- what a channel declares about itself on registration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ChannelManifest(BaseModel):
+    """Describes a channel's capabilities, identity policies, and delivery config."""
+
+    channel_key: str = Field(..., min_length=1, max_length=128)
+    display_name: str = Field(..., min_length=1, max_length=256)
+    gateway_family: str = Field(..., min_length=1, max_length=64)
+
+    supports_media: bool = False
+    supports_reactions: bool = False
+    supports_voice: bool = False
+    supports_rich_text: bool = False
+    max_message_length: int | None = None
+
+    phone_identity_unification: bool = False
+    session_isolation: bool = False
+    provides_channel_id: bool = False
+
+    delivery_webhook: str | None = None
+    delivery_protocol: str = "hermes"
+    delivery_aliases: list[str] = Field(default_factory=list)
+    home_chat_id: str | None = None
+
+    platform_hint: str = ""
+    pii_safe: bool = True

apsimo/channels/migrations/001_channels_schema.sql

@@ -0,0 +1,12 @@
+-- Channel registration store: any channel can self-register with Colony.
+CREATE TABLE IF NOT EXISTS channels (
+    channel_key    TEXT PRIMARY KEY,
+    display_name   TEXT NOT NULL,
+    gateway_family TEXT NOT NULL,
+    manifest_json  TEXT NOT NULL,
+    channel_token  TEXT NOT NULL,
+    registered_at  TEXT NOT NULL,
+    last_seen_at   TEXT,
+    status         TEXT NOT NULL DEFAULT 'active'
+        CHECK(status IN ('active', 'inactive', 'revoked'))
+);