argus-gate 1.0.0__py3-none-any.whl

argus_gate/__init__.py

@@ -0,0 +1,97 @@
+"""Argus Gate: capability token enforcement for AI agents.
+
+The package implements the token protocol, the action binding, the executor
+guard, and the issuer. Policy evaluation and evidence records come from the
+Argus SDK and Argus Core; this package does not re-implement them.
+"""
+
+from .action import (
+    GateAction,
+    action_hash,
+    canonical_action_bytes,
+    proposal_bytes,
+    proposal_hash,
+    to_proposal,
+)
+from .enterprise import AgentRegistry, AgentRecord, ShadowAgentError
+from .constraints import apply_constraints, decode_constraints, encode_constraints
+from .errors import RejectionCode, TokenProtocolError, VerificationResult
+from .executor import ExecutorGuard, ExecutorSettings
+from .gtv import encode as gtv_encode
+from .issuer import DEFAULT_TTL_US, MAX_TTL_US, TokenIssuer
+from .keys import (
+    ROLE_GATE_ISSUER,
+    ROLE_OPERATOR_AUTHORITY,
+    STATUS_ACTIVE,
+    STATUS_REVOKED,
+    STATUS_SUPERSEDED,
+    KeyEpochEntry,
+    KeyEpochList,
+)
+from .replay import ReplayStore, SQLiteReplayStore, open_replay_store
+from .revocation import KIND_SEQUENCE_FROM, KIND_TOKEN_ID, RevocationEntry, RevocationSet
+from .scope import Scope, scope_for
+from .token import (
+    DECISION_APPROVE,
+    DECISION_MODIFY,
+    FLAG_HOLDER_BINDING,
+    TOKEN_TYPE_CAPABILITY,
+    TOKEN_TYPE_OPERATOR_OVERRIDE,
+    CapabilityToken,
+    now_us,
+)
+
+try:
+    from importlib.metadata import version as _dist_version
+
+    __version__ = _dist_version("argus-gate")
+except Exception:
+    __version__ = "1.0.0rc1"
+
+__all__ = [
+    "AgentRecord",
+    "AgentRegistry",
+    "CapabilityToken",
+    "ShadowAgentError",
+    "DECISION_APPROVE",
+    "DECISION_MODIFY",
+    "DEFAULT_TTL_US",
+    "ExecutorGuard",
+    "ExecutorSettings",
+    "FLAG_HOLDER_BINDING",
+    "GateAction",
+    "KeyEpochEntry",
+    "KeyEpochList",
+    "KIND_SEQUENCE_FROM",
+    "KIND_TOKEN_ID",
+    "MAX_TTL_US",
+    "ROLE_GATE_ISSUER",
+    "ROLE_OPERATOR_AUTHORITY",
+    "RejectionCode",
+    "ReplayStore",
+    "RevocationEntry",
+    "RevocationSet",
+    "SQLiteReplayStore",
+    "STATUS_ACTIVE",
+    "STATUS_REVOKED",
+    "STATUS_SUPERSEDED",
+    "Scope",
+    "TOKEN_TYPE_CAPABILITY",
+    "TOKEN_TYPE_OPERATOR_OVERRIDE",
+    "TokenIssuer",
+    "TokenProtocolError",
+    "VerificationResult",
+    "__version__",
+    "action_hash",
+    "apply_constraints",
+    "canonical_action_bytes",
+    "decode_constraints",
+    "encode_constraints",
+    "gtv_encode",
+    "now_us",
+    "open_replay_store",
+    "proposal_bytes",
+    "proposal_hash",
+    "scope_for",
+    "to_proposal",
+]

argus_gate/action.py

@@ -0,0 +1,196 @@
+"""Canonical actions and their mapping to proposals and hashes.
+
+A Gate action is (action_class, target, arguments). Its canonical bytes are
+the action class byte, the target with a uint16 length, and the arguments as
+GTV. `action_hash = SHA-256(0x10 || canonical action bytes)` binds the token
+to the exact action the executor will perform.
+
+The action-to-proposal mapping produces a conformant proposal for policy
+evaluation and the evidence record: the scalar leaves of the arguments value
+become typed parameters, named by their RFC 6901 JSON Pointer with the leading
+slash removed and slashes replaced by underscores (an alias map may override
+the name). Leaves whose derived name is not a policy-language identifier are
+omitted from the parameter map; they remain covered by the action hash. Nulls
+and containers produce no parameters.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Mapping, Sequence
+
+from argus.protocol.proposal import (
+    ActionClass,
+    Parameter,
+    ParameterType,
+    ProposedAction,
+    Provenance,
+    is_identifier,
+)
+
+from .gtv import encode as gtv_encode
+
+__all__ = [
+    "ACTION_HASH_DOMAIN",
+    "GateAction",
+    "action_hash",
+    "canonical_action_bytes",
+    "leaf_parameters",
+    "parameter_pointers",
+    "proposal_bytes",
+    "proposal_hash",
+    "to_proposal",
+]
+
+ACTION_HASH_DOMAIN = 0x10
+PROPOSAL_HASH_DOMAIN = 0x02
+_MAX_PARAMETERS = 128
+
+_ZERO32 = bytes(32)
+_ZERO64 = bytes(64)
+
+
+@dataclass(frozen=True)
+class GateAction:
+    """One agent action in canonical form.
+
+    Attributes:
+        action_class: An action class code (0x01 to 0x06).
+        target: The adapter-canonical target string.
+        arguments: The JSON value the executor will consume.
+        confidence: Model-reported confidence where the surface provides it.
+        timestamp: Host monotonic counter where the surface provides it.
+        context_hash: SHA-256 of the inference context where available.
+        model_identity_hash: SHA-256 of the model identifier where available.
+        model_weight_hash: SHA-256 of the model weights where available.
+        previous_attestation: Previous evidence record hash where available.
+        host_attestation: Host attestation signature where available.
+    """
+
+    action_class: int
+    target: str
+    arguments: Any
+    confidence: float = 0.0
+    timestamp: int = 0
+    context_hash: bytes = _ZERO32
+    model_identity_hash: bytes = _ZERO32
+    model_weight_hash: bytes = _ZERO32
+    previous_attestation: bytes = _ZERO32
+    host_attestation: bytes = _ZERO64
+
+
+def canonical_action_bytes(action: GateAction) -> bytes:
+    """The canonical action bytes (section 7.1 of the token protocol)."""
+    target_bytes = action.target.encode("utf-8")
+    if len(target_bytes) > 0xFFFF:
+        raise ValueError("target exceeds the uint16 length field")
+    return (
+        struct.pack("<B", action.action_class)
+        + struct.pack("<H", len(target_bytes))
+        + target_bytes
+        + gtv_encode(action.arguments)
+    )
+
+
+def action_hash(action: GateAction) -> bytes:
+    """SHA-256(0x10 || canonical action bytes)."""
+    return hashlib.sha256(bytes([ACTION_HASH_DOMAIN]) + canonical_action_bytes(action)).digest()
+
+
+def _pointer_escape(token: str) -> str:
+    return token.replace("~", "~0").replace("/", "~1")
+
+
+def _iter_leaves(value: Any, pointer: str) -> Iterator[tuple[str, Any]]:
+    if value is None:
+        return
+    if isinstance(value, dict):
+        for key in value:
+            if not isinstance(key, str):
+                raise ValueError("arguments object keys must be strings")
+            yield from _iter_leaves(value[key], pointer + "/" + _pointer_escape(key))
+    elif isinstance(value, (list, tuple)):
+        for index, element in enumerate(value):
+            yield from _iter_leaves(element, pointer + "/" + str(index))
+    else:
+        yield pointer, value
+
+
+def _parameter_name(pointer: str, aliases: Mapping[str, str] | None) -> str | None:
+    if aliases and pointer in aliases:
+        return aliases[pointer]
+    if not pointer:
+        return None
+    name = pointer[1:].replace("/", "_")
+    return name if is_identifier(name) else None
+
+
+def leaf_parameters(
+    arguments: Any, aliases: Mapping[str, str] | None = None
+) -> tuple[Parameter, ...]:
+    """Map the scalar leaves of an arguments value to typed parameters,
+    ascending by name bytes. Leaves without an identifier-safe name are
+    omitted; they remain covered by the action hash."""
+    parameters: list[Parameter] = []
+    seen: set[str] = set()
+    for pointer, value in _iter_leaves(arguments, ""):
+        name = _parameter_name(pointer, aliases)
+        if name is None or name in seen:
+            continue
+        seen.add(name)
+        if isinstance(value, bool):
+            parameter = Parameter(name=name, type_tag=ParameterType.BOOL, value=value)
+        elif isinstance(value, (int, float)):
+            parameter = Parameter(name=name, type_tag=ParameterType.FLOAT64, value=float(value))
+        elif isinstance(value, str):
+            parameter = Parameter(name=name, type_tag=ParameterType.STRING, value=value)
+        else:
+            raise ValueError(f"unsupported leaf type at {pointer!r}: {type(value).__name__}")
+        parameters.append(parameter)
+    if len(parameters) > _MAX_PARAMETERS:
+        raise ValueError(f"parameter map exceeds {_MAX_PARAMETERS} entries")
+    parameters.sort(key=lambda parameter: parameter.name.encode("utf-8"))
+    return tuple(parameters)
+
+
+def parameter_pointers(
+    arguments: Any, aliases: Mapping[str, str] | None = None
+) -> dict[str, str]:
+    """Map parameter names back to their JSON Pointers (the inverse of the
+    leaf mapping), for constraint translation."""
+    pointers: dict[str, str] = {}
+    for pointer, value in _iter_leaves(arguments, ""):
+        name = _parameter_name(pointer, aliases)
+        if name is not None and name not in pointers:
+            pointers[name] = pointer
+    return pointers
+
+
+def to_proposal(action: GateAction, aliases: Mapping[str, str] | None = None) -> ProposedAction:
+    """Build the conformant proposal for policy evaluation and evidence."""
+    return ProposedAction(
+        action_class=ActionClass(action.action_class),
+        target=action.target,
+        parameters=list(leaf_parameters(action.arguments, aliases)),
+        confidence=action.confidence,
+        timestamp=action.timestamp,
+        context_hash=action.context_hash,
+        provenance=Provenance(
+            model_identity_hash=action.model_identity_hash,
+            model_weight_hash=action.model_weight_hash,
+            previous_attestation=action.previous_attestation,
+            host_attestation=action.host_attestation,
+        ),
+    )
+
+
+def proposal_bytes(action: GateAction, aliases: Mapping[str, str] | None = None) -> bytes:
+    """The canonical proposal encoding (EST-SPEC-012 section 6)."""
+    return to_proposal(action, aliases).encode()
+
+
+def proposal_hash(action: GateAction, aliases: Mapping[str, str] | None = None) -> bytes:
+    """SHA-256(0x02 || canonical proposal encoding)."""
+    return to_proposal(action, aliases).proposal_hash()

argus_gate/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Model SDK middleware: gate tool calls from OpenAI, Anthropic, and Google.
+
+Every tool call a model emits is evaluated against the operator policy
+before it executes; an approved call proceeds carrying a single-use
+capability token that the executor verifies. The adapters are transport
+neutral: they parse each provider's native shapes, gate through the shared
+GateCore, and return the provider's own result formats.
+"""
+
+from .code_mode import CodeModeAdapter, CodeModeOutcome
+from .model import ModelGate, ModelToolCall, ModelToolOutcome
+
+__all__ = [
+    "CodeModeAdapter",
+    "CodeModeOutcome",
+    "ModelGate",
+    "ModelToolCall",
+    "ModelToolOutcome",
+]

argus_gate/adapters/anthropic.py

@@ -0,0 +1,89 @@
+"""Anthropic tool-calling middleware: messages API tool_use shapes.
+
+The adapter parses each tool_use block, gates it through the shared
+ModelGate, executes approved calls, and returns tool_result blocks. A denied
+call never executes and returns a typed error result.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+from .model import ModelGate, ModelGateError, ModelToolCall
+
+__all__ = ["gated_messages_round", "parse_tool_use", "tool_result_block"]
+
+
+def parse_tool_use(content_blocks: list) -> list[ModelToolCall]:
+    """Normalize tool_use blocks from a messages API response."""
+    return [
+        ModelToolCall(
+            provider="anthropic",
+            name=block["name"],
+            arguments=block.get("input", {}),
+            call_id=block.get("id"),
+        )
+        for block in content_blocks
+        if isinstance(block, dict) and block.get("type") == "tool_use"
+    ]
+
+
+def tool_result_block(tool_use_id: str, content: Any, is_error: bool = False) -> dict:
+    return {
+        "type": "tool_result",
+        "tool_use_id": tool_use_id,
+        "content": content if isinstance(content, str) else json.dumps(content),
+        "is_error": is_error,
+    }
+
+
+def gated_messages_round(
+    create_fn: Callable,
+    *,
+    gate: ModelGate,
+    execute_tool: Callable[[str, Any], Any],
+    max_rounds: int = 6,
+    **create_kwargs,
+) -> dict:
+    """Drive a gated messages API loop with a client-shaped callable.
+
+    ``create_fn`` accepts model, messages, tools, and any provider kwargs and
+    returns a messages-shaped dict with a content block list.
+    """
+    transcript = list(create_kwargs["messages"])
+    decisions: list[dict] = []
+    for _ in range(max_rounds):
+        response = create_fn(**{**create_kwargs, "messages": transcript})
+        content = response.get("content") or []
+        calls = parse_tool_use(content)
+        if not calls:
+            return {"message": response, "decisions": decisions, "transcript": transcript}
+        transcript.append({"role": "assistant", "content": content})
+        result_blocks: list[dict] = []
+        for call in calls:
+            outcome = gate.evaluate(call)
+            decisions.append(
+                {
+                    "provider": "anthropic",
+                    "tool": call.name,
+                    "decision": outcome.decision,
+                    "reason": outcome.reason,
+                    "clause_ref": outcome.clause_ref,
+                }
+            )
+            if not outcome.approved:
+                result_blocks.append(
+                    tool_result_block(call.call_id, outcome.denial_content(), is_error=True)
+                )
+                continue
+            executed, value = gate.execute(outcome, execute_tool)
+            if executed:
+                result_blocks.append(
+                    tool_result_block(call.call_id, json.dumps({"result": value}))
+                )
+            else:
+                content = value if isinstance(value, dict) else {"error": "execution_failed"}
+                result_blocks.append(tool_result_block(call.call_id, content, is_error=True))
+        transcript.append({"role": "user", "content": result_blocks})
+    raise ModelGateError(f"exceeded max_rounds {max_rounds}")

argus_gate/adapters/code_mode.py

@@ -0,0 +1,123 @@
+"""The Code Mode adapter: the dispatch-shim for Cloudflare/Anthropic Code Mode.
+
+Code Mode turns tools into a generated TypeScript API and runs the model's
+script in a sandbox, with intermediate data kept out of the context. The
+Gate's mapping: both designs keep a per-call dispatch point, so per-call
+enforcement survives unchanged.
+
+The adapter sits between the model's generated script and the sandbox
+executor. The script declares its intended actions (file_read, file_write,
+network, exec) as a sequence of GrantRequests. The adapter evaluates each
+request against the policy, issues a capability token per granted action,
+and the sandbox executes only the granted actions. An unbounded script is
+refused certification; the abstention surface is INCONCLUSIVE fail-closed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from ..action import GateAction
+from ..errors import RejectionCode, VerificationResult
+from ..guards.base import GuardOutcome
+from ..guards.sandbox import GRANT_CLASSES, GrantRequest, SandboxGuard, analyze_script
+from ..mcp import GateCore
+
+__all__ = ["CodeModeAdapter", "CodeModeOutcome"]
+
+
+@dataclass(frozen=True)
+class CodeModeOutcome:
+    """The outcome of one code mode evaluation."""
+
+    certified: bool
+    grants: tuple[tuple[str, str], ...]  # (kind, token_bytes_b64)
+    refusals: tuple[tuple[str, str], ...]  # (kind, reason)
+    script_status: str  # "certified" | "refused"
+
+
+class CodeModeAdapter:
+    """The dispatch-shim adapter: evaluates a code mode script's intended
+    actions against the policy and issues capability tokens per grant."""
+
+    def __init__(
+        self,
+        core: GateCore,
+        sandbox: SandboxGuard,
+    ) -> None:
+        self.core = core
+        self.sandbox = sandbox
+
+    def evaluate_script(
+        self,
+        source: str,
+        requests: list[GrantRequest],
+        request_id_base: int = 1,
+    ) -> CodeModeOutcome:
+        """Evaluate a code mode script: certify the script, then evaluate
+        each intended action. Returns the grants and refusals.
+
+        The script is certified if it has no unbounded constructs (via
+        analyze_script). A refused script is not evaluated further; every
+        intended action is refused with SCRIPT_NOT_CERTIFIED.
+        """
+        analysis = analyze_script(source)
+        if not analysis.certified:
+            refusals = tuple(
+                (req.kind, "SCRIPT_NOT_CERTIFIED") for req in requests
+            )
+            return CodeModeOutcome(
+                certified=False,
+                grants=(),
+                refusals=refusals,
+                script_status="refused",
+            )
+
+        grants: list[tuple[str, str]] = []
+        refusals: list[tuple[str, str]] = []
+
+        for i, req in enumerate(requests):
+            request_id = request_id_base + i
+            if req.kind not in GRANT_CLASSES:
+                refusals.append((req.kind, f"unknown grant kind {req.kind!r}"))
+                continue
+            outcome = self.core.evaluate_call(
+                req.kind, req.detail, request_id
+            )
+            if outcome.approved:
+                grants.append((req.kind, outcome.token.encode().hex()))
+            else:
+                refusals.append((req.kind, outcome.reason or "POLICY_DENIED"))
+
+        return CodeModeOutcome(
+            certified=len(refusals) == 0,
+            grants=tuple(grants),
+            refusals=tuple(refusals),
+            script_status="certified" if len(refusals) == 0 else "refused",
+        )
+
+    def execute_grants(
+        self,
+        grants: tuple[tuple[str, str], ...],
+        run_fns: dict[str, Callable[[Any], Any]],
+    ) -> dict[str, GuardOutcome]:
+        """Execute each granted action with its capability token.
+
+        Each grant carries the hex-encoded token bytes and the action kind.
+        run_fns maps kind -> the function to execute with the granted detail.
+        Returns a dict of kind -> GuardOutcome for each executed grant.
+        """
+        results: dict[str, GuardOutcome] = {}
+        for kind, token_hex in grants:
+            token_bytes = bytes.fromhex(token_hex)
+            if kind not in run_fns:
+                continue
+            # Reconstruct a GrantRequest for the sandbox guard
+            # The detail is not carried in the grant; the caller must
+            # reconstruct it from the original script context.
+            # This is a design boundary: the adapter issues the grant,
+            # the caller executes it with the detail from the script.
+            request = GrantRequest(kind=kind, detail={}, request_id=None)
+            results[kind] = self.sandbox.grant(token_bytes, request, run_fns[kind])
+        return results

argus_gate/adapters/google.py

@@ -0,0 +1,89 @@
+"""Google tool-calling middleware: generateContent functionCall shapes.
+
+The adapter parses each functionCall part, gates it through the shared
+ModelGate, and returns functionResponse parts. Protocol-conformant with the
+OpenAI and Anthropic adapters: the same policy produces the same decisions.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+from .model import ModelGate, ModelGateError, ModelToolCall
+
+__all__ = ["function_response_part", "gated_generate_round", "parse_function_calls"]
+
+
+def parse_function_calls(response: dict) -> list[ModelToolCall]:
+    """Normalize functionCall parts from a generateContent response."""
+    calls: list[ModelToolCall] = []
+    for candidate in response.get("candidates") or []:
+        content = candidate.get("content") or {}
+        for part in content.get("parts") or []:
+            function_call = part.get("functionCall")
+            if isinstance(function_call, dict) and function_call.get("name"):
+                calls.append(
+                    ModelToolCall(
+                        provider="google",
+                        name=function_call["name"],
+                        arguments=function_call.get("args", {}),
+                        call_id=function_call.get("id"),
+                    )
+                )
+    return calls
+
+
+def function_response_part(name: str, result: Any) -> dict:
+    return {
+        "functionResponse": {
+            "name": name,
+            "response": result if isinstance(result, dict) else {"result": result},
+        }
+    }
+
+
+def gated_generate_round(
+    create_fn: Callable,
+    *,
+    gate: ModelGate,
+    execute_tool: Callable[[str, Any], Any],
+    max_rounds: int = 6,
+    **create_kwargs,
+) -> dict:
+    """Drive a gated generateContent loop with a client-shaped callable."""
+    contents = list(create_kwargs["contents"])
+    decisions: list[dict] = []
+    for _ in range(max_rounds):
+        response = create_fn(**{**create_kwargs, "contents": contents})
+        calls = parse_function_calls(response)
+        candidates = response.get("candidates") or []
+        model_content = (candidates[0].get("content") if candidates else {}) or {}
+        if not calls:
+            return {"message": response, "decisions": decisions, "contents": contents}
+        contents.append(model_content)
+        response_parts: list[dict] = []
+        for call in calls:
+            outcome = gate.evaluate(call)
+            decisions.append(
+                {
+                    "provider": "google",
+                    "tool": call.name,
+                    "decision": outcome.decision,
+                    "reason": outcome.reason,
+                    "clause_ref": outcome.clause_ref,
+                }
+            )
+            if not outcome.approved:
+                response_parts.append(
+                    function_response_part(call.name, json.loads(outcome.denial_content()))
+                )
+                continue
+            executed, value = gate.execute(outcome, execute_tool)
+            if executed:
+                response_parts.append(function_response_part(call.name, {"result": value}))
+            else:
+                content = value if isinstance(value, dict) else {"error": "execution_failed"}
+                response_parts.append(function_response_part(call.name, content))
+        contents.append({"role": "user", "parts": response_parts})
+    raise ModelGateError(f"exceeded max_rounds {max_rounds}")