Skip to content

PIP Types

Policy Information Point (PIP) types for building PDP integration requests and interpreting responses. Implements RFC-005: Policy Definition, Distribution and Enforcement.

RFC-005 Implementation

This API implements the PIP request/response format from RFC-005 §5–§7.

Quick Start

from capiscio_sdk.pip import (
    PIPRequest, PIPResponse,
    SubjectAttributes, ActionAttributes,
    ResourceAttributes, ContextAttributes,
    EnforcementMode, Obligation,
)

# Build a policy decision request
request = PIPRequest(
    subject=SubjectAttributes(
        did="did:web:example.com:agents:bot",
        badge_jti="badge-session-id",
        ial="1",
        trust_level="DV",
    ),
    action=ActionAttributes(operation="POST /api/v1/badges"),
    resource=ResourceAttributes(identifier="/api/v1/badges"),
    context=ContextAttributes(
        txn_id="txn-uuid",
        enforcement_mode=EnforcementMode.GUARD,
    ),
)

# Serialize to dict for your PDP client
payload = request.to_dict()

# Parse PDP response
response = PIPResponse.from_dict({
    "decision": "ALLOW",
    "decision_id": "eval-uuid",
    "obligations": [],
    "ttl": 300,
})

if response.is_allow:
    print("Access granted")

EnforcementMode

capiscio_sdk.pip.EnforcementMode

Bases: Enum

PEP enforcement strictness level (RFC-008 §10.5 total order).

Values

OBSERVE: Log only, never block. GUARD: Block on verification failure, log PDP denials. DELEGATE: Block on verification + PDP deny, best-effort obligations. STRICT: Block on everything including obligation failures.

stricter_than 

stricter_than(other: EnforcementMode) -> bool

Return True if this mode is stricter than other.

from_env classmethod 

from_env() -> EnforcementMode

Read enforcement mode from CAPISCIO_ENFORCEMENT_MODE.

Returns OBSERVE (the safe rollout default) when the variable is unset or empty.

Raises:

Type Description
ValueError

If the variable is set but not a recognised mode.

Request Types

PIPRequest

capiscio_sdk.pip.PIPRequest dataclass

RFC-005 §5 Decision Request.

Attributes:

Name Type Description
subject SubjectAttributes

Agent identity attributes.
action ActionAttributes

Attempted operation.
resource ResourceAttributes

Target resource.
context ContextAttributes

Correlation / authority context.
environment EnvironmentAttributes

PEP runtime context.
pip_version str

Protocol version (auto-set).

to_dict 

to_dict() -> Dict[str, Any]

Serialise to PIP wire format (JSON-compatible dict).

Automatically populates context.txn_id (UUID v7 via :func:uuid.uuid7 when available, else :func:uuid.uuid4) and environment.time (ISO 8601 UTC) if not already set.

SubjectAttributes

capiscio_sdk.pip.SubjectAttributes dataclass

Identifies the acting agent (RFC-005 §5.1).

Attributes:

Name Type Description
did str

Agent DID from badge sub claim.
badge_jti str

Badge jti claim.
ial str

Identity Assurance Level (e.g. "IAL-1").
trust_level str

Badge trust level string (e.g. "1", "2", "3").

ActionAttributes

capiscio_sdk.pip.ActionAttributes dataclass

Identifies what is being attempted (RFC-005 §5.1).

Attributes:

Name Type Description
operation str

Tool name, HTTP method+route, etc.
capability_class Optional[str]

None in badge-only mode (RFC-008).

ResourceAttributes

capiscio_sdk.pip.ResourceAttributes dataclass

Identifies the target resource (RFC-005 §5.1).

Attributes:

Name Type Description
identifier str

Target resource URI.

ContextAttributes

capiscio_sdk.pip.ContextAttributes dataclass

Correlation and authority context (RFC-005 §5.1).

Envelope-sourced fields (envelope_id, delegation_depth, constraints, parent_constraints) MUST be None in badge-only mode. They serialise as JSON null, not absent keys.

Attributes:

Name Type Description
txn_id str

Transaction correlation ID (UUID v7 recommended).
enforcement_mode Union[str, EnforcementMode]

PEP-level enforcement mode string.
hop_id Optional[str]

Optional hop attestation ID.
envelope_id Optional[str]

None until RFC-008.
delegation_depth Optional[int]

None until RFC-008.
constraints Optional[Any]

None until RFC-008.
parent_constraints Optional[Any]

None until RFC-008.

EnvironmentAttributes

capiscio_sdk.pip.EnvironmentAttributes dataclass

PEP runtime context (RFC-005 §5.1).

Attributes:

Name Type Description
workspace Optional[str]

Optional workspace / tenant identifier.
pep_id Optional[str]

Optional PEP instance identifier.
time Optional[str]

ISO 8601 timestamp (RECOMMENDED). Auto-populated by :meth:PIPRequest.to_dict if not set.

Response Types

PIPResponse

capiscio_sdk.pip.PIPResponse dataclass

RFC-005 §6.1 Decision Response.

Attributes:

Name Type Description
decision str

"ALLOW" or "DENY" (PDP values only).
decision_id str

Globally unique decision identifier.
obligations List[Obligation]

List of obligations to enforce.
reason str

Optional human-readable explanation.
ttl Optional[int]

Optional cache lifetime in seconds.

Obligation

capiscio_sdk.pip.Obligation dataclass

A conditional contract returned by the PDP (RFC-005 §7.1).

Attributes:

Name Type Description
type str

Obligation type (e.g. "rate_limit", "audit_log").
params Optional[Dict[str, Any]]

Opaque parameters dictionary. None serialises as JSON null.

Constants

Constant Value Description
PIP_VERSION "capiscio.pip.v1" Protocol version string
DECISION_ALLOW "ALLOW" PDP authorized the request
DECISION_DENY "DENY" PDP rejected the request
DECISION_OBSERVE "ALLOW_OBSERVE" PEP-only: PDP unavailable in EM-OBSERVE mode