lcp-reference-platform 1.0.0__py3-none-any.whl

lcp_platform/auth.py

@@ -0,0 +1,202 @@
+"""Authentication for the reference platform."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+
+from .api_keys import hash_api_key, verify_api_key
+from .config import PlatformConfig
+from .secrets import FileSecretProvider
+from .storage import Store
+
+
+def header(headers: dict[str, str], name: str) -> str | None:
+    """Read an HTTP header without relying on dictionary casing."""
+    name = name.lower()
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+class AuthenticationError(ValueError):
+    """Raised when an LCP request cannot be authenticated."""
+
+    def __init__(self, message: str, code: str = "LCP-002"):
+        self.code = code
+        super().__init__(message)
+
+
+def canonical_bytes(timestamp: str, idempotency_key: str | None, body: bytes) -> bytes:
+    return f"{timestamp}\n{idempotency_key or ''}\n".encode("utf-8") + body
+
+
+def signature_for(
+    secret: str | bytes | bytearray | memoryview,
+    timestamp: str,
+    idempotency_key: str | None,
+    body: bytes,
+) -> str:
+    secret_bytes = (
+        secret
+        if isinstance(secret, bytes)
+        else secret.tobytes()
+        if isinstance(secret, memoryview)
+        else bytes(secret)
+        if isinstance(secret, bytearray)
+        else secret.encode("utf-8")
+    )
+    return hmac.new(
+        secret_bytes,
+        canonical_bytes(timestamp, idempotency_key, body),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def _timestamp_is_fresh(timestamp: str, max_skew_seconds: int) -> bool:
+    from datetime import datetime, timezone
+    try:
+        signed_at = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    if signed_at.tzinfo is None:
+        return False
+    now = datetime.now(timezone.utc)
+    return abs((now - signed_at.astimezone(timezone.utc)).total_seconds()) <= max_skew_seconds
+
+
+class Authenticator:
+    def __init__(self, store: Store, config: PlatformConfig):
+        self.store = store
+        self.config = config
+        self.secrets = FileSecretProvider(config.secrets_file)
+
+    def principal(self, sender_id: str) -> dict[str, object] | None:
+        row = self.store.get_credential(sender_id)
+        principal = dict(row) if row else None
+        external = self.secrets.get(sender_id)
+        if external:
+            principal = principal or {
+                "sender_id": sender_id,
+                "tenant_id": external.get("tenant_id", "default"),
+                "scopes_json": "[]",
+                "active": 1,
+            }
+            for field in ("hmac_secret", "previous_hmac_secret"):
+                if field in external:
+                    principal[field] = external[field]
+            if external.get("api_key"):
+                principal["api_key_salt"], principal["api_key_hash"] = hash_api_key(
+                    str(external["api_key"])
+                )
+            if "scopes" in external:
+                principal["scopes_json"] = json.dumps(external["scopes"])
+            principal.setdefault("hmac_secret", None)
+            principal.setdefault("previous_hmac_secret", None)
+            principal.setdefault("api_key_hash", None)
+            principal.setdefault("api_key_salt", None)
+        return principal
+
+    def authenticate(
+        self,
+        *,
+        sender_id: str | None,
+        headers: dict[str, str],
+        body: bytes,
+        idempotency_key: str | None = None,
+        mutating: bool = False,
+        required_scope: str | None = None,
+    ) -> str:
+        """Authenticate and return the authenticated sender ID."""
+        header_sender = header(headers, "X-LCP-Sender-Id")
+        if sender_id and header_sender and sender_id != header_sender:
+            raise AuthenticationError("Sender header does not match the envelope", "LCP-002")
+        sender_id = sender_id or header_sender
+        authorization = header(headers, "Authorization") or ""
+        if not sender_id and authorization.lower().startswith("bearer "):
+            sender_id = self.store.find_sender_for_api_key(authorization[7:].strip())
+        if not sender_id:
+            raise AuthenticationError("Sender identity is required")
+
+        if not self.config.require_auth:
+            return sender_id
+
+        credential = self.principal(sender_id)
+        if not credential:
+            raise AuthenticationError("Unknown sender", "LCP-002")
+
+        if authorization.lower().startswith("bearer "):
+            presented = authorization[7:].strip()
+            salt = credential.get("api_key_salt")
+            stored = credential.get("api_key_hash")
+            if not verify_api_key(
+                presented, str(salt) if salt else None, str(stored) if stored else None
+            ):
+                raise AuthenticationError("Invalid bearer credential", "LCP-012")
+        else:
+            timestamp = header(headers, "X-LCP-Timestamp")
+            signature = header(headers, "X-LCP-Signature")
+            header_key = header(headers, "X-LCP-Idempotency-Key")
+            if not timestamp or not signature:
+                raise AuthenticationError("HMAC headers are required", "LCP-012")
+            if not _timestamp_is_fresh(timestamp, self.config.replay_window_seconds):
+                raise AuthenticationError("Timestamp is outside the replay window", "LCP-012")
+            if mutating and not header_key:
+                raise AuthenticationError("Idempotency header is required", "LCP-012")
+            if header_key and idempotency_key and header_key != idempotency_key:
+                raise AuthenticationError("Header/body idempotency keys differ", "LCP-012")
+            candidate_secrets = [
+                credential["hmac_secret"],
+                credential["previous_hmac_secret"],
+            ]
+            if not any(
+                secret
+                and hmac.compare_digest(
+                    signature.lower(),
+                    signature_for(secret, timestamp, header_key, body),
+                )
+                for secret in candidate_secrets
+            ):
+                raise AuthenticationError("Invalid HMAC signature", "LCP-012")
+
+        if required_scope and not self.has_scope(sender_id, required_scope):
+            raise AuthenticationError("Sender is not authorized for this operation", "LCP-002")
+        return sender_id
+
+    def has_scope(self, sender_id: str, required_scope: str) -> bool:
+        scopes = self.scopes_for(sender_id)
+        return "*" in scopes or required_scope in scopes or "platform:admin" in scopes
+
+    def secret_for(self, sender_id: str) -> str | None:
+        credential = self.principal(sender_id)
+        if not credential or not credential.get("hmac_secret"):
+            return None
+        value = credential["hmac_secret"]
+        if isinstance(value, memoryview):
+            return value.tobytes().decode("utf-8")
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+        return str(value)
+
+    def tenant_for(self, sender_id: str) -> str | None:
+        principal = self.principal(sender_id)
+        return str(principal["tenant_id"]) if principal and principal.get("tenant_id") else None
+
+    def scopes_for(self, sender_id: str) -> set[str]:
+        principal = self.principal(sender_id)
+        if not principal:
+            return set()
+        raw_scopes = principal.get("scopes_json", "[]")
+        if isinstance(raw_scopes, memoryview):
+            raw_scopes = raw_scopes.tobytes().decode("utf-8")
+        elif isinstance(raw_scopes, bytes):
+            raw_scopes = raw_scopes.decode("utf-8")
+        try:
+            decoded = json.loads(str(raw_scopes))
+        except (TypeError, ValueError):
+            return set()
+        if not isinstance(decoded, list) or not all(isinstance(scope, str) for scope in decoded):
+            return set()
+        return set(decoded)

lcp_platform/config.py

@@ -0,0 +1,157 @@
+"""Reference platform configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+
+
+def _bool(name: str, default: bool) -> bool:
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    return value.lower() in {"1", "true", "yes", "on"}
+
+
+def _csv(name: str, default: str = "") -> tuple[str, ...]:
+    return tuple(value.strip() for value in os.environ.get(name, default).split(",") if value.strip())
+
+
+@dataclass(frozen=True)
+class PlatformConfig:
+    database_path: Path
+    database_url: str | None = None
+    schema_root: Path | None = None
+    secrets_file: Path | None = None
+    pii_encryption_key: str | None = None
+    host: str = "127.0.0.1"
+    port: int = 8080
+    platform_id: str = "platform_001"
+    routing_tenant_id: str = "default"
+    require_auth: bool = True
+    replay_window_seconds: int = 300
+    webhook_timeout_seconds: float = 10.0
+    max_delivery_attempts: int = 5
+    worker_interval_seconds: float = 1.0
+    max_body_bytes: int = 2_000_000
+    max_header_bytes: int = 16_384
+    max_webhook_response_bytes: int = 262_144
+    rate_limit_per_minute: int = 600
+    allow_insecure_webhooks: bool = False
+    webhook_host_allowlist: tuple[str, ...] = ()
+    test_mode: bool = False
+    attachment_directory: Path = Path("./data/lcp-attachments")
+    max_attachment_bytes: int = 100 * 1024 * 1024
+    allowed_attachment_content_types: tuple[str, ...] = (
+        "application/pdf",
+        "image/jpeg",
+        "image/png",
+        "image/webp",
+        "text/plain",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    )
+    # Production object-storage profile. The file backend remains the default
+    # for local and sandbox use; the S3-compatible backend requires all of the
+    # object/KMS/residency fields below when selected outside test mode.
+    attachment_backend: str = "file"
+    attachment_scanner: str = "none"
+    attachment_scan_required: bool = False
+    attachment_residency: str | None = None
+    attachment_allowed_residencies: tuple[str, ...] = ()
+    attachment_object_bucket: str | None = None
+    attachment_object_prefix: str = "lcp/attachments"
+    attachment_object_endpoint_url: str | None = None
+    attachment_object_region: str | None = None
+    attachment_object_kms_key_id: str | None = None
+    attachment_object_residency: str | None = None
+    attachment_clamav_socket: str | None = None
+    attachment_clamav_host: str = "127.0.0.1"
+    attachment_clamav_port: int = 3310
+
+    def __post_init__(self) -> None:
+        if self.max_body_bytes <= 0 or self.max_header_bytes <= 0:
+            raise ValueError("Request size limits must be positive")
+        if self.max_webhook_response_bytes <= 0:
+            raise ValueError("Webhook response limit must be positive")
+        if self.max_attachment_bytes <= 0:
+            raise ValueError("Attachment size limit must be positive")
+        if self.rate_limit_per_minute <= 0:
+            raise ValueError("Rate limit must be positive")
+        if not self.require_auth and not self.test_mode:
+            raise ValueError("Authentication may only be disabled in test mode")
+        if not self.test_mode and not self.pii_encryption_key:
+            raise ValueError("LCP_PII_ENCRYPTION_KEY is required outside test mode")
+        if self.allow_insecure_webhooks and not self.test_mode:
+            raise ValueError("Insecure webhooks may only be enabled in test mode")
+        if self.attachment_backend not in {"file", "s3"}:
+            raise ValueError("LCP_ATTACHMENT_BACKEND must be 'file' or 's3'")
+        if self.attachment_scanner not in {"none", "clamav"}:
+            raise ValueError("LCP_ATTACHMENT_SCANNER must be 'clamav' or 'none'")
+        if self.attachment_scan_required and self.attachment_scanner == "none" and not self.test_mode:
+            raise ValueError("A production attachment scan is required when LCP_ATTACHMENT_SCAN_REQUIRED is enabled")
+        if self.attachment_backend == "s3" and not self.test_mode:
+            missing = {
+                "LCP_ATTACHMENT_OBJECT_BUCKET": self.attachment_object_bucket,
+                "LCP_ATTACHMENT_OBJECT_KMS_KEY_ID": self.attachment_object_kms_key_id,
+                "LCP_ATTACHMENT_OBJECT_RESIDENCY": self.attachment_object_residency,
+            }
+            if any(not value for value in missing.values()):
+                raise ValueError(f"S3 attachment backend requires: {', '.join(key for key, value in missing.items() if not value)}")
+            if not self.attachment_scan_required:
+                raise ValueError("S3 attachment backend requires malware scanning")
+            if self.attachment_allowed_residencies and self.attachment_object_residency.upper() not in {
+                value.strip().upper() for value in self.attachment_allowed_residencies
+            }:
+                raise ValueError("Object-store residency is not in the allowed residency policy")
+
+    @classmethod
+    def from_env(cls) -> "PlatformConfig":
+        return cls(
+            database_path=Path(os.environ.get("LCP_DATABASE_PATH", "./data/lcp.sqlite3")),
+            database_url=os.environ.get("LCP_DATABASE_URL"),
+            schema_root=Path(os.environ["LCP_SCHEMA_DIR"])
+            if os.environ.get("LCP_SCHEMA_DIR")
+            else None,
+            secrets_file=Path(os.environ["LCP_SECRETS_FILE"])
+            if os.environ.get("LCP_SECRETS_FILE")
+            else None,
+            pii_encryption_key=os.environ.get("LCP_PII_ENCRYPTION_KEY"),
+            host=os.environ.get("LCP_HOST", "127.0.0.1"),
+            port=int(os.environ.get("LCP_PORT", "8080")),
+            platform_id=os.environ.get("LCP_PLATFORM_ID", "platform_001"),
+            routing_tenant_id=os.environ.get("LCP_ROUTING_TENANT_ID", "default"),
+            require_auth=_bool("LCP_REQUIRE_AUTH", True),
+            replay_window_seconds=int(os.environ.get("LCP_REPLAY_WINDOW_SECONDS", "300")),
+            webhook_timeout_seconds=float(os.environ.get("LCP_WEBHOOK_TIMEOUT_SECONDS", "10")),
+            max_delivery_attempts=int(os.environ.get("LCP_MAX_DELIVERY_ATTEMPTS", "5")),
+            worker_interval_seconds=float(os.environ.get("LCP_WORKER_INTERVAL_SECONDS", "1")),
+            max_body_bytes=int(os.environ.get("LCP_MAX_BODY_BYTES", "2000000")),
+            max_header_bytes=int(os.environ.get("LCP_MAX_HEADER_BYTES", "16384")),
+            max_webhook_response_bytes=int(os.environ.get("LCP_MAX_WEBHOOK_RESPONSE_BYTES", "262144")),
+            rate_limit_per_minute=int(os.environ.get("LCP_RATE_LIMIT_PER_MINUTE", "600")),
+            allow_insecure_webhooks=_bool("LCP_ALLOW_INSECURE_WEBHOOKS", False),
+            webhook_host_allowlist=_csv("LCP_WEBHOOK_HOST_ALLOWLIST"),
+            test_mode=_bool("LCP_TEST_MODE", False),
+            attachment_directory=Path(os.environ.get("LCP_ATTACHMENT_DIRECTORY", "./data/lcp-attachments")),
+            max_attachment_bytes=int(os.environ.get("LCP_MAX_ATTACHMENT_BYTES", str(100 * 1024 * 1024))),
+            allowed_attachment_content_types=_csv(
+                "LCP_ALLOWED_ATTACHMENT_CONTENT_TYPES",
+                "application/pdf,image/jpeg,image/png,image/webp,text/plain,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            ),
+            attachment_backend=os.environ.get("LCP_ATTACHMENT_BACKEND", "file").lower(),
+            attachment_scanner=os.environ.get("LCP_ATTACHMENT_SCANNER", "clamav").lower(),
+            attachment_scan_required=_bool("LCP_ATTACHMENT_SCAN_REQUIRED", True),
+            attachment_residency=os.environ.get("LCP_ATTACHMENT_RESIDENCY"),
+            attachment_allowed_residencies=_csv("LCP_ATTACHMENT_ALLOWED_RESIDENCIES"),
+            attachment_object_bucket=os.environ.get("LCP_ATTACHMENT_OBJECT_BUCKET"),
+            attachment_object_prefix=os.environ.get("LCP_ATTACHMENT_OBJECT_PREFIX", "lcp/attachments"),
+            attachment_object_endpoint_url=os.environ.get("LCP_ATTACHMENT_OBJECT_ENDPOINT_URL"),
+            attachment_object_region=os.environ.get("LCP_ATTACHMENT_OBJECT_REGION"),
+            attachment_object_kms_key_id=os.environ.get("LCP_ATTACHMENT_OBJECT_KMS_KEY_ID"),
+            attachment_object_residency=os.environ.get("LCP_ATTACHMENT_OBJECT_RESIDENCY"),
+            attachment_clamav_socket=os.environ.get("LCP_ATTACHMENT_CLAMAV_SOCKET"),
+            attachment_clamav_host=os.environ.get("LCP_ATTACHMENT_CLAMAV_HOST", "127.0.0.1"),
+            attachment_clamav_port=int(os.environ.get("LCP_ATTACHMENT_CLAMAV_PORT", "3310")),
+        )

lcp_platform/crypto.py

@@ -0,0 +1,94 @@
+"""Application-level encryption for persisted LCP envelopes."""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+class EnvelopeCryptoError(ValueError):
+    """Raised when an encrypted envelope cannot be decoded."""
+
+
+class EnvelopeCipher:
+    """Encrypt JSON envelopes while preserving an explicit version marker."""
+
+    _prefix = "enc:v1:"
+    _aad = b"lcp-persisted-envelope:v1"
+
+    def __init__(self, key: str | bytes | None):
+        self._key = self._decode_key(key) if key else None
+
+    @staticmethod
+    def _decode_key(key: str | bytes) -> bytes:
+        raw = key.encode("ascii") if isinstance(key, str) else key
+        try:
+            decoded = base64.b64decode(
+                raw + b"=" * (-len(raw) % 4), altchars=b"-_", validate=True
+            )
+        except (ValueError, UnicodeEncodeError) as exc:
+            raise EnvelopeCryptoError(
+                "LCP_PII_ENCRYPTION_KEY must be URL-safe base64"
+            ) from exc
+        if len(decoded) != 32:
+            raise EnvelopeCryptoError(
+                "LCP_PII_ENCRYPTION_KEY must decode to exactly 32 bytes"
+            )
+        return decoded
+
+    @property
+    def enabled(self) -> bool:
+        return self._key is not None
+
+    def encode(self, value: dict[str, Any]) -> str:
+        plaintext = json.dumps(
+            value, separators=(",", ":"), ensure_ascii=False
+        ).encode("utf-8")
+        if not self._key:
+            return plaintext.decode("utf-8")
+        nonce = secrets.token_bytes(12)
+        ciphertext = AESGCM(self._key).encrypt(nonce, plaintext, self._aad)
+        return self._prefix + base64.urlsafe_b64encode(nonce + ciphertext).decode("ascii")
+
+    def encrypt_bytes(self, value: bytes, *, aad: bytes = b"lcp-persisted-attachment:v1") -> bytes:
+        """Encrypt binary PII such as an uploaded contract or call record."""
+        if not self._key:
+            return value
+        nonce = secrets.token_bytes(12)
+        return b"encb:v1:" + nonce + AESGCM(self._key).encrypt(nonce, value, aad)
+
+    def decrypt_bytes(self, value: bytes, *, aad: bytes = b"lcp-persisted-attachment:v1") -> bytes:
+        if not value.startswith(b"encb:v1:"):
+            if self._key:
+                raise EnvelopeCryptoError("Unencrypted attachment encountered while encryption is required")
+            return value
+        if not self._key:
+            raise EnvelopeCryptoError("Encrypted attachment requires LCP_PII_ENCRYPTION_KEY")
+        packed = value[len(b"encb:v1:"):]
+        try:
+            return AESGCM(self._key).decrypt(packed[:12], packed[12:], aad)
+        except Exception as exc:
+            raise EnvelopeCryptoError("Persisted attachment authentication failed") from exc
+
+    def decode(self, value: str) -> dict[str, Any]:
+        if not value.startswith(self._prefix):
+            if self._key:
+                raise EnvelopeCryptoError(
+                    "Unencrypted persisted envelope encountered while encryption is required"
+                )
+            return json.loads(value)
+        if not self._key:
+            raise EnvelopeCryptoError("Encrypted envelope requires LCP_PII_ENCRYPTION_KEY")
+        try:
+            packed = base64.urlsafe_b64decode(value[len(self._prefix) :])
+            plaintext = AESGCM(self._key).decrypt(packed[:12], packed[12:], self._aad)
+            decoded = json.loads(plaintext)
+        except Exception as exc:
+            raise EnvelopeCryptoError("Persisted envelope authentication failed") from exc
+        if not isinstance(decoded, dict):
+            raise EnvelopeCryptoError("Persisted envelope must be a JSON object")
+        return decoded

lcp_platform/database.py

@@ -0,0 +1,18 @@
+"""Database backend selection."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .config import PlatformConfig
+from .storage import Store
+
+
+def create_store(config: PlatformConfig) -> Any:
+    if config.database_url:
+        from .postgres import PostgresStore
+        return PostgresStore(
+            config.database_url,
+            pii_encryption_key=config.pii_encryption_key,
+        )
+    return Store(config.database_path, pii_encryption_key=config.pii_encryption_key)