dbl-gateway 0.3.2__py3-none-any.whl

dbl_gateway/auth.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    mode: str
+    issuer: str
+    audience: str
+    jwks_url: str
+    allowed_tenants: tuple[str, ...]
+    allow_all_tenants: bool
+    tenant_claim: str
+    role_claims: tuple[str, ...]
+    role_map: dict[str, list[str]] | None
+    dev_actor: str
+    dev_roles: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Actor:
+    actor_id: str
+    tenant_id: str
+    client_id: str
+    roles: tuple[str, ...]
+    raw_claims: dict[str, Any]
+
+
+class AuthError(Exception):
+    pass
+
+
+class ForbiddenError(Exception):
+    pass
+
+
+_JWKS_BY_URL: dict[str, dict[str, Any]] = {}
+_JWKS_TS_BY_URL: dict[str, float] = {}
+_JWKS_CACHE_TTL_S: float = 300.0
+
+
+def load_auth_config() -> AuthConfig:
+    mode = os.getenv("DBL_GATEWAY_AUTH_MODE", "dev").strip().lower()
+    issuer = os.getenv("DBL_GATEWAY_OIDC_ISSUER", "").strip()
+    audience = os.getenv("DBL_GATEWAY_OIDC_AUDIENCE", "").strip()
+    jwks_url = os.getenv("DBL_GATEWAY_OIDC_JWKS_URL", "").strip()
+    allowed_tenants_raw = os.getenv("DBL_GATEWAY_ALLOWED_TENANTS", "*").strip()
+    tenant_claim = os.getenv("DBL_GATEWAY_TENANT_CLAIM", "tid").strip() or "tid"
+    role_claims_raw = os.getenv("DBL_GATEWAY_ROLE_CLAIMS", "roles").strip()
+    role_map_raw = os.getenv("DBL_GATEWAY_ROLE_MAP", "").strip()
+
+    dev_actor = os.getenv("DBL_GATEWAY_DEV_ACTOR", "dev-user").strip()
+    dev_roles_raw = os.getenv(
+        "DBL_GATEWAY_DEV_ROLES",
+        "gateway.intent.write,gateway.decision.write,gateway.snapshot.read",
+    ).strip()
+    dev_roles = tuple([r.strip() for r in dev_roles_raw.split(",") if r.strip()])
+
+    allow_all_tenants = allowed_tenants_raw == "*" or allowed_tenants_raw == ""
+    allowed_tenants = tuple([t.strip() for t in allowed_tenants_raw.split(",") if t.strip()])
+    role_claims = tuple([c.strip() for c in role_claims_raw.split(",") if c.strip()])
+    role_map = _parse_role_map(role_map_raw)
+
+    return AuthConfig(
+        mode=mode,
+        issuer=issuer,
+        audience=audience,
+        jwks_url=jwks_url,
+        allowed_tenants=allowed_tenants,
+        allow_all_tenants=allow_all_tenants,
+        tenant_claim=tenant_claim,
+        role_claims=role_claims,
+        role_map=role_map,
+        dev_actor=dev_actor,
+        dev_roles=dev_roles,
+    )
+
+
+def require_roles(actor: Actor, required: Sequence[str]) -> None:
+    missing = [r for r in required if r not in actor.roles]
+    if missing:
+        raise ForbiddenError(f"missing roles: {', '.join(missing)}")
+
+
+def require_tenant(actor: Actor, cfg: AuthConfig | None = None) -> None:
+    cfg = cfg or load_auth_config()
+    if cfg.allow_all_tenants:
+        return
+    if actor.tenant_id in cfg.allowed_tenants:
+        return
+    raise ForbiddenError("tenant not allowed")
+
+
+async def authenticate_request(headers: Mapping[str, str], cfg: AuthConfig | None = None) -> Actor:
+    cfg = cfg or load_auth_config()
+    if cfg.mode == "dev":
+        return _authenticate_dev(headers, cfg)
+    if cfg.mode == "oidc":
+        claims = await _authenticate_oidc(headers, cfg)
+        return _authorize_oidc_claims(claims, cfg)
+    raise AuthError(f"unsupported auth mode: {cfg.mode}")
+
+
+def _authenticate_dev(headers: Mapping[str, str], cfg: AuthConfig) -> Actor:
+    actor_id = headers.get("x-dev-actor", cfg.dev_actor).strip() or cfg.dev_actor
+    roles_header = headers.get("x-dev-roles", "")
+    roles = cfg.dev_roles
+    if roles_header.strip():
+        roles = tuple([r.strip() for r in roles_header.split(",") if r.strip()])
+
+    return Actor(
+        actor_id=actor_id,
+        tenant_id=headers.get("x-dev-tenant", "dev-tenant").strip() or "dev-tenant",
+        client_id=headers.get("x-dev-client", "dev-client").strip() or "dev-client",
+        roles=roles,
+        raw_claims={"dev": True},
+    )
+
+
+async def _authenticate_oidc(headers: Mapping[str, str], cfg: AuthConfig) -> dict[str, Any]:
+    if not cfg.issuer or not cfg.audience or not cfg.jwks_url:
+        raise AuthError("OIDC config incomplete: issuer, audience, jwks_url required")
+
+    auth = headers.get("authorization", "")
+    if not auth.lower().startswith("bearer "):
+        raise AuthError("missing bearer token")
+    token = auth.split(" ", 1)[1].strip()
+    if not token:
+        raise AuthError("missing bearer token")
+
+    jwks = await _get_jwks(cfg.jwks_url)
+    try:
+        from jose import jwk, jwt
+        from jose.exceptions import JWTError
+
+        header = jwt.get_unverified_header(token)
+        try:
+            jwk_data = _select_jwk(header, jwks)
+        except AuthError as exc:
+            if str(exc) != "no matching JWKS key for kid":
+                raise
+            jwks = await _get_jwks(cfg.jwks_url, force=True)
+            jwk_data = _select_jwk(header, jwks)
+        key = jwk.construct(jwk_data)
+        claims = jwt.decode(
+            token,
+            key,
+            algorithms=["RS256"],
+            issuer=cfg.issuer,
+            audience=cfg.audience,
+            options={
+                "verify_aud": True,
+                "verify_iss": True,
+                "verify_exp": True,
+                "verify_nbf": True,
+                "verify_iat": True,
+            },
+            leeway=60,
+        )
+    except ImportError as exc:
+        raise AuthError("OIDC auth requires python-jose") from exc
+    except JWTError as exc:
+        raise AuthError(f"invalid token: {exc}") from exc
+
+    return dict(claims)
+
+
+async def _get_jwks(jwks_url: str, *, force: bool = False) -> dict[str, Any]:
+    global _JWKS_BY_URL, _JWKS_TS_BY_URL
+    now = time.time()
+    if not force and jwks_url in _JWKS_BY_URL:
+        ts = _JWKS_TS_BY_URL.get(jwks_url, 0.0)
+        if (now - ts) < _JWKS_CACHE_TTL_S:
+            return _JWKS_BY_URL[jwks_url]
+
+    try:
+        import httpx
+    except ImportError as exc:
+        raise AuthError("OIDC auth requires httpx") from exc
+
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        resp = await client.get(jwks_url)
+        resp.raise_for_status()
+        jwks = resp.json()
+
+    if not isinstance(jwks, dict) or "keys" not in jwks:
+        raise AuthError("invalid JWKS payload")
+
+    _JWKS_BY_URL[jwks_url] = jwks
+    _JWKS_TS_BY_URL[jwks_url] = now
+    return jwks
+
+
+def _pick_first_str(claims: Mapping[str, Any], keys: list[str], default: str) -> str:
+    for k in keys:
+        v = claims.get(k)
+        if isinstance(v, str) and v.strip():
+            return v.strip()
+    return default
+
+
+def _select_jwk(header: Mapping[str, Any], jwks: Mapping[str, Any]) -> Mapping[str, Any]:
+    kid = header.get("kid")
+    alg = header.get("alg")
+    if alg != "RS256":
+        raise AuthError("unsupported token algorithm")
+    if not isinstance(kid, str) or not kid.strip():
+        raise AuthError("token missing kid")
+    keys = jwks.get("keys")
+    if not isinstance(keys, list):
+        raise AuthError("invalid JWKS payload")
+    for key in keys:
+        if isinstance(key, Mapping) and key.get("kid") == kid:
+            return key
+    raise AuthError("no matching JWKS key for kid")
+
+
+def _authorize_oidc_claims(claims: Mapping[str, Any], cfg: AuthConfig) -> Actor:
+    actor_id = _pick_first_str(claims, ["oid", "sub"], default="")
+    if not actor_id:
+        raise AuthError("token missing actor id claim (oid/sub)")
+    tenant_id = _pick_first_str(claims, [cfg.tenant_claim], default="unknown")
+    client_id = _pick_first_str(claims, ["azp", "appid"], default="unknown")
+    roles = _extract_roles(claims, cfg.role_claims)
+    roles = _apply_role_map(roles, cfg.role_map)
+    return Actor(
+        actor_id=actor_id,
+        tenant_id=tenant_id,
+        client_id=client_id,
+        roles=roles,
+        raw_claims=dict(claims),
+    )
+
+
+def _extract_roles(claims: Mapping[str, Any], claim_names: Sequence[str]) -> tuple[str, ...]:
+    roles: list[str] = []
+    for claim in claim_names:
+        v = claims.get(claim)
+        if isinstance(v, list):
+            for item in v:
+                if isinstance(item, str) and item.strip():
+                    roles.append(item.strip())
+        elif isinstance(v, str) and v.strip():
+            for item in v.replace(",", " ").split():
+                if item.strip():
+                    roles.append(item.strip())
+    seen: set[str] = set()
+    unique: list[str] = []
+    for r in roles:
+        if r not in seen:
+            seen.add(r)
+            unique.append(r)
+    return tuple(unique)
+
+
+def _apply_role_map(roles: tuple[str, ...], role_map: dict[str, list[str]] | None) -> tuple[str, ...]:
+    if role_map is None:
+        return roles
+    mapped: list[str] = []
+    for role in roles:
+        if role in role_map:
+            mapped.extend(role_map[role])
+        else:
+            mapped.append(role)
+    seen: set[str] = set()
+    unique: list[str] = []
+    for role in mapped:
+        if role not in seen:
+            seen.add(role)
+            unique.append(role)
+    return tuple(unique)
+
+
+def _parse_role_map(role_map_raw: str) -> dict[str, list[str]] | None:
+    if role_map_raw == "":
+        return None
+    try:
+        parsed = json.loads(role_map_raw)
+    except json.JSONDecodeError as exc:
+        raise AuthError("DBL_GATEWAY_ROLE_MAP must be valid JSON") from exc
+    if not isinstance(parsed, dict):
+        raise AuthError("DBL_GATEWAY_ROLE_MAP must be a JSON object")
+    role_map: dict[str, list[str]] = {}
+    for key, value in parsed.items():
+        if isinstance(value, str):
+            role_map[str(key)] = [value]
+        elif isinstance(value, list):
+            mapped = [v for v in value if isinstance(v, str) and v.strip()]
+            role_map[str(key)] = mapped
+    return role_map

dbl_gateway/capabilities.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import os
+
+
+def get_capabilities() -> dict[str, object]:
+    models = _available_models()
+    allowed_model_ids = [model["model_id"] for model in models]
+    default_model_id = _default_model_id(allowed_model_ids)
+    return {
+        "allowed_model_ids": allowed_model_ids,
+        "default_model_id": default_model_id,
+    }
+
+
+def _available_models() -> list[dict[str, str]]:
+    models: list[dict[str, str]] = []
+    if _get_openai_key():
+        for model_id in _openai_models():
+            models.append({"provider": "openai", "model_id": model_id})
+    if _get_anthropic_key():
+        for model_id in _anthropic_models():
+            models.append({"provider": "anthropic", "model_id": model_id})
+    return models
+
+
+def resolve_provider(model_id: str) -> tuple[str | None, str | None]:
+    if model_id in _openai_models():
+        if not _get_openai_key():
+            return None, "provider.missing_credentials"
+        return "openai", None
+    if model_id in _anthropic_models():
+        if not _get_anthropic_key():
+            return None, "provider.missing_credentials"
+        return "anthropic", None
+    return None, "model.unavailable"
+
+
+def _openai_models() -> list[str]:
+    chat_models = _parse_csv("OPENAI_CHAT_MODEL_IDS")
+    if not chat_models:
+        chat_models = _parse_csv("OPENAI_MODEL_IDS")
+    if not chat_models:
+        chat_models = ["gpt-4o-mini"]
+    response_models = _parse_csv("OPENAI_RESPONSES_MODEL_IDS") or []
+    combined: list[str] = []
+    seen: set[str] = set()
+    for model_id in chat_models + response_models:
+        if model_id in seen:
+            continue
+        seen.add(model_id)
+        combined.append(model_id)
+    return combined
+
+
+def _anthropic_models() -> list[str]:
+    models = _parse_csv("ANTHROPIC_MODEL_IDS")
+    return models or ["claude-3-haiku-20240307"]
+
+
+def _default_model_id(allowed: list[str]) -> str | None:
+    if not allowed:
+        return None
+    return allowed[0]
+
+
+def _get_openai_key() -> str:
+    return os.getenv("OPENAI_API_KEY", "").strip()
+
+
+def _get_anthropic_key() -> str:
+    return os.getenv("ANTHROPIC_API_KEY", "").strip()
+
+
+def _parse_csv(name: str) -> list[str]:
+    raw = os.getenv(name, "").strip()
+    if not raw:
+        return []
+    return [item.strip() for item in raw.split(",") if item.strip()]

dbl_gateway/digest.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dbl_core import DblEvent, DblEventKind
+from dbl_core.events.canonical import canonicalize_value, digest_bytes, json_dumps
+
+__all__ = ["event_digest", "v_digest"]
+
+
+def event_digest(kind: str, correlation_id: str, payload: dict[str, Any]) -> tuple[str, int]:
+    event_kind = DblEventKind(kind)
+    event_payload = _strip_obs(payload)
+    event = DblEvent(event_kind=event_kind, correlation_id=correlation_id, data=event_payload)
+    canonical_json = event.to_json(include_observational=False)
+    return event.digest(), len(canonical_json)
+
+
+def v_digest(indexed: list[tuple[int, str]]) -> str:
+    items = [{"index": idx, "digest": digest} for idx, digest in indexed]
+    canonical = canonicalize_value(items)
+    canonical_json = json_dumps(canonical)
+    return digest_bytes(canonical_json)
+
+
+def _strip_obs(payload: dict[str, Any]) -> dict[str, Any]:
+    if "_obs" not in payload:
+        return payload
+    sanitized = dict(payload)
+    sanitized.pop("_obs", None)
+    return sanitized

dbl_gateway/execution.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from .adapters.execution_adapter_kl import KlExecutionAdapter, schedule_execution
+from .ports.execution_port import ExecutionResult
+
+__all__ = [
+    "ExecutionResult",
+    "KlExecutionAdapter",
+    "run_execution",
+    "schedule_execution",
+]
+
+
+async def run_execution(intent_event):
+    return await KlExecutionAdapter().run(intent_event)

dbl_gateway/governance.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .adapters.policy_adapter_dbl_policy import (
+    ALLOWED_CONTEXT_KEYS,
+    DblPolicyAdapter,
+    _build_policy_context,
+)
+from .ports.policy_port import DecisionResult
+
+__all__ = [
+    "ALLOWED_CONTEXT_KEYS",
+    "DecisionResult",
+    "DblPolicyAdapter",
+    "_build_policy_context",
+    "decide_for_intent",
+]
+
+
+def decide_for_intent(authoritative_input):
+    return DblPolicyAdapter().decide(authoritative_input)

dbl_gateway/models.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class EventRecord(TypedDict):
+    index: int
+    kind: str
+    lane: str
+    actor: str
+    intent_type: str
+    stream_id: str
+    correlation_id: str
+    payload: dict[str, Any]
+    digest: str
+    canon_len: int
+
+
+class Snapshot(TypedDict):
+    length: int
+    offset: int
+    limit: int
+    v_digest: str
+    events: list[EventRecord]

dbl_gateway/ports/__init__.py

@@ -0,0 +1,11 @@
+from .execution_port import ExecutionPort, ExecutionResult
+from .policy_port import DecisionResult, PolicyPort
+from .store_port import StorePort
+
+__all__ = [
+    "DecisionResult",
+    "ExecutionPort",
+    "ExecutionResult",
+    "PolicyPort",
+    "StorePort",
+]

dbl_gateway/ports/execution_port.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Protocol
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    output_text: str | None = None
+    provider: str | None = None
+    model_id: str | None = None
+    trace: dict[str, Any] | None = None
+    trace_digest: str | None = None
+    error: dict[str, Any] | None = None
+
+
+class ExecutionPort(Protocol):
+    async def run(self, intent_event: Mapping[str, Any]) -> ExecutionResult:
+        ...

dbl_gateway/ports/policy_port.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Protocol
+
+
+@dataclass(frozen=True)
+class DecisionResult:
+    decision: str
+    reason_codes: list[str]
+    policy_id: str | None = None
+    policy_version: int | None = None
+    gate_event: object | None = None
+
+
+class PolicyPort(Protocol):
+    def decide(self, authoritative_input: Mapping[str, Any]) -> DecisionResult:
+        ...

dbl_gateway/ports/store_port.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..models import EventRecord, Snapshot
+
+
+class StorePort(Protocol):
+    def append(
+        self,
+        *,
+        kind: str,
+        lane: str,
+        actor: str,
+        intent_type: str,
+        stream_id: str,
+        correlation_id: str,
+        payload: dict[str, object],
+    ) -> EventRecord:
+        ...
+
+    def snapshot(
+        self,
+        *,
+        limit: int,
+        offset: int,
+        stream_id: str | None = None,
+        lane: str | None = None,
+    ) -> Snapshot:
+        ...
+
+    def close(self) -> None:
+        ...

dbl_gateway/projection.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Iterable
+
+from dbl_core import DblEvent, DblEventKind, GateDecision
+from dbl_main import Phase, RunnerStatus, State, project_state
+
+
+def project_runner_state(events: Iterable[dict[str, object]]) -> State:
+    dbl_events: list[DblEvent] = []
+    for event in events:
+        kind = DblEventKind(str(event.get("kind")))
+        correlation_id = str(event.get("correlation_id"))
+        data = event.get("payload")
+        if kind == DblEventKind.DECISION and isinstance(data, dict):
+            decision = str(data.get("decision", "DENY"))
+            reason_codes = data.get("reason_codes")
+            if isinstance(reason_codes, list) and reason_codes:
+                reason_code = str(reason_codes[0])
+            else:
+                reason_code = str(data.get("reason_code", "unspecified"))
+            reason_message = data.get("reason_message") if isinstance(data.get("reason_message"), str) else None
+            data = GateDecision(decision, reason_code, reason_message)
+        dbl_events.append(DblEvent(event_kind=kind, correlation_id=correlation_id, data=data))
+    return project_state(dbl_events)
+
+
+def state_payload(state: State) -> dict[str, object]:
+    return {
+        "phase": state.phase.value,
+        "runner_status": state.runner_status.value,
+        "t_index": state.t_index,
+        "note": state.note,
+    }

dbl_gateway/providers/__init__.py

@@ -0,0 +1 @@
+__all__ = ["openai", "anthropic", "errors"]

dbl_gateway/providers/anthropic.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from .errors import ProviderError
+
+
+def execute(message: str, model_id: str) -> str:
+    api_key = os.getenv("ANTHROPIC_API_KEY", "").strip()
+    if not api_key:
+        raise ProviderError("missing Anthropic credentials")
+    headers = {
+        "x-api-key": api_key,
+        "anthropic-version": "2023-06-01",
+    }
+    payload: dict[str, Any] = {
+        "model": model_id,
+        "max_tokens": 256,
+        "messages": [
+            {"role": "user", "content": [{"type": "text", "text": message}]}
+        ],
+    }
+    with httpx.Client(timeout=60.0) as client:
+        resp = client.post("https://api.anthropic.com/v1/messages", json=payload, headers=headers)
+        if resp.status_code >= 400:
+            _raise_anthropic(resp)
+        data = resp.json()
+    return _parse_text(data)
+
+
+def _parse_text(data: dict[str, Any]) -> str:
+    content = data.get("content", [])
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for entry in content:
+        if entry.get("type") == "text":
+            text = entry.get("text")
+            if isinstance(text, str):
+                parts.append(text)
+    return "\n".join(parts)
+
+
+def _raise_anthropic(resp: httpx.Response) -> None:
+    code = None
+    msg = None
+    try:
+        j = resp.json()
+        err = j.get("error") if isinstance(j, dict) else None
+        if isinstance(err, dict):
+            code = err.get("type")
+            msg = err.get("message")
+    except Exception:
+        pass
+    detail = msg or resp.text[:500]
+    raise ProviderError(
+        f"anthropic.messages failed: {detail}",
+        status_code=resp.status_code,
+        code=str(code) if code else None,
+    )

dbl_gateway/providers/errors.py

@@ -0,0 +1,5 @@
+class ProviderError(RuntimeError):
+    def __init__(self, message: str, status_code: int | None = None, code: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code