vinctor-core 0.2.0__py3-none-any.whl

vinctor_core/__init__.py

@@ -0,0 +1,44 @@
+"""Vinctor deterministic authorization core."""
+
+from vinctor_core.audit import AuditEventInput, build_audit_event
+from vinctor_core.enforce import evaluate_enforce
+from vinctor_core.models import (
+    AuditEvent,
+    Boundary,
+    BoundaryRegistrationInput,
+    DecisionResult,
+    EnforceInput,
+    Grant,
+    PolicyInput,
+    PolicyResult,
+)
+from vinctor_core.policy import evaluate_policy
+from vinctor_core.registry import (
+    BoundaryRegistry,
+    disable_boundary,
+    enable_boundary,
+    get_boundary_for_workspace,
+    register_boundary,
+)
+from vinctor_core.scope import scope_subsumes
+
+__all__ = [
+    "AuditEvent",
+    "AuditEventInput",
+    "Boundary",
+    "BoundaryRegistrationInput",
+    "BoundaryRegistry",
+    "DecisionResult",
+    "EnforceInput",
+    "Grant",
+    "PolicyInput",
+    "PolicyResult",
+    "build_audit_event",
+    "disable_boundary",
+    "enable_boundary",
+    "evaluate_enforce",
+    "evaluate_policy",
+    "get_boundary_for_workspace",
+    "register_boundary",
+    "scope_subsumes",
+]

vinctor_core/audit.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from secrets import token_urlsafe
+
+from vinctor_core.models import AuditEvent, DecisionResult
+
+
+@dataclass(frozen=True)
+class AuditEventInput:
+    decision: DecisionResult
+    event_id: str | None = None
+    created_at: datetime | None = None
+    enforcing_principal: str | None = None
+    identity_proven: bool = False
+    token_id: str | None = None
+
+
+def build_audit_event(audit_input: AuditEventInput) -> AuditEvent:
+    decision = audit_input.decision
+    boundary = decision.boundary
+    boundary_id = boundary.boundary_id if boundary else decision.attempted_boundary_id
+
+    return AuditEvent(
+        event_id=audit_input.event_id or _new_event_id(),
+        event_type="action_permitted" if decision.decision == "permit" else "action_denied",
+        decision=decision.decision,
+        reason=decision.reason,
+        workspace_id=decision.workspace_id,
+        agent_id=decision.agent_id,
+        grant_id=decision.grant_id,
+        grant_ref=decision.grant_ref,
+        action=decision.action,
+        resource=decision.resource,
+        scope_attempted=decision.scope_attempted,
+        scope_matched=decision.scope_matched,
+        boundary_id=boundary_id,
+        runtime=boundary.runtime if boundary else None,
+        boundary_type=boundary.boundary_type if boundary else None,
+        created_at=audit_input.created_at or datetime.now(UTC),
+        enforcing_principal=audit_input.enforcing_principal,
+        identity_proven=audit_input.identity_proven,
+        token_id=audit_input.token_id,
+    )
+
+
+# Operator-only audit for security-relevant pre-grant-evaluation rejections
+# (ADR 0008). These never alter the caller-facing response.
+EVENT_ACCESS_REJECTED = "access_rejected"
+EVENT_AUTH_FAILED = "auth_failed"
+EVENT_GRANT_ISSUE_REJECTED = "grant_issue_rejected"
+EVENT_SUBJECT_TOKEN_MINTED = "subject_token_minted"
+
+# Coarse `reason_code` enum for rejection events. Intentionally low-cardinality
+# so the audit trail carries the security signal without leaking specifics.
+REASON_AGENT_GRANT_MISMATCH = "agent_grant_mismatch"
+REASON_AUTH_FAILED = "auth_failed"
+REASON_SCOPE_OUTSIDE_ISSUABLE_BOUNDS = "scope_outside_issuable_bounds"
+REASON_ISSUABLE_BOUNDS_NOT_FOUND = "issuable_bounds_not_found"
+REASON_TTL_EXCEEDS_ISSUABLE_MAX = "ttl_exceeds_issuable_max"
+REASON_SUBJECT_TOKEN_INVALID = "subject_token_invalid"
+REASON_SUBJECT_TOKEN_REQUIRED = "subject_token_required"
+REASON_POP_REQUIRED = "pop_required"
+
+
+def build_rejection_audit_event(
+    *,
+    reason_code: str,
+    workspace_id: str,
+    agent_id: str,
+    created_at: datetime,
+    event_type: str = EVENT_ACCESS_REJECTED,
+    action: str = "",
+    resource: str = "",
+    scope_attempted: str | None = None,
+    boundary_id: str | None = None,
+    enforcing_principal: str | None = None,
+    event_id: str | None = None,
+    occurrence_count: int | None = None,
+    first_seen_at: datetime | None = None,
+    last_seen_at: datetime | None = None,
+) -> AuditEvent:
+    """Build an audit event for a request rejected BEFORE grant-scope evaluation.
+
+    Per ADR 0008, security-relevant pre-grant rejections (e.g. an agent naming a
+    grant that is not its own, or an operator over-issuing beyond an agent's
+    bounds) are recorded for the operator, while the caller-facing response stays
+    generic and leak-free. The event carries a coarse ``reason_code`` (also
+    mirrored into ``reason`` so existing reason-keyed audit columns/queries keep
+    working) and deliberately discloses no grant identifiers:
+    ``grant_id``/``grant_ref`` are empty so the offending grant is never revealed
+    in the trail. ``action``/``resource`` are retained as operator-only audit
+    signal (they are not a caller leak). ``scope_attempted`` defaults to
+    ``action:resource`` (the enforce case) but can be set explicitly (e.g. the
+    requested scopes of an issuance). The authentication-failure path additionally
+    carries an aggregated ``occurrence_count`` with the window's first/last-seen
+    timestamps.
+    """
+    return AuditEvent(
+        event_id=event_id or _new_event_id(),
+        event_type=event_type,
+        decision="deny",
+        reason=reason_code,
+        workspace_id=workspace_id,
+        agent_id=agent_id,
+        grant_id="",
+        grant_ref="",
+        action=action,
+        resource=resource,
+        scope_attempted=scope_attempted if scope_attempted is not None else f"{action}:{resource}",
+        scope_matched=None,
+        boundary_id=boundary_id,
+        runtime=None,
+        boundary_type=None,
+        created_at=created_at,
+        enforcing_principal=enforcing_principal,
+        reason_code=reason_code,
+        occurrence_count=occurrence_count,
+        first_seen_at=first_seen_at,
+        last_seen_at=last_seen_at,
+    )
+
+
+def _new_event_id() -> str:
+    return f"evt_{token_urlsafe(12)}"

vinctor_core/enforce.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from vinctor_core.models import Boundary, DecisionResult, EnforceInput
+from vinctor_core.scope import (
+    attempted_scope,
+    is_valid_grant_scope,
+    is_valid_requested_action,
+    is_valid_requested_resource,
+    match_scope,
+)
+
+
+def evaluate_enforce(enforce_input: EnforceInput) -> DecisionResult:
+    grant = enforce_input.grant
+    scope_attempted = attempted_scope(enforce_input.action, enforce_input.resource)
+
+    boundary_result = _resolve_boundary(enforce_input)
+    if isinstance(boundary_result, DecisionResult):
+        return boundary_result
+    boundary = boundary_result
+
+    if not is_valid_requested_action(enforce_input.action):
+        return _deny(enforce_input, "invalid_action", scope_attempted, boundary=boundary)
+    if not is_valid_requested_resource(enforce_input.resource):
+        return _deny(enforce_input, "invalid_resource", scope_attempted, boundary=boundary)
+
+    if grant.status == "revoked":
+        return _deny(enforce_input, "grant_revoked", scope_attempted, boundary=boundary)
+    if grant.status == "expired":
+        return _deny(enforce_input, "grant_expired", scope_attempted, boundary=boundary)
+    if grant.status != "active":
+        return _deny(enforce_input, "grant_not_active", scope_attempted, boundary=boundary)
+    if grant.expires_at is not None and grant.expires_at <= enforce_input.now:
+        return _deny(enforce_input, "grant_expired", scope_attempted, boundary=boundary)
+    if any(not is_valid_grant_scope(scope) for scope in grant.scopes):
+        return _deny(enforce_input, "invalid_grant_scope", scope_attempted, boundary=boundary)
+
+    matched = match_scope(grant.scopes, enforce_input.action, enforce_input.resource)
+    if matched is None:
+        return _deny(enforce_input, "action_denied", scope_attempted, boundary=boundary)
+
+    return DecisionResult(
+        decision="permit",
+        reason="permitted",
+        grant_id=grant.grant_id,
+        grant_ref=grant.grant_ref,
+        workspace_id=grant.workspace_id,
+        agent_id=grant.agent_id,
+        action=enforce_input.action,
+        resource=enforce_input.resource,
+        scope_attempted=scope_attempted,
+        scope_matched=matched,
+        boundary=boundary,
+        attempted_boundary_id=enforce_input.boundary_id,
+    )
+
+
+def _resolve_boundary(enforce_input: EnforceInput) -> Boundary | DecisionResult | None:
+    boundary_id = enforce_input.boundary_id
+    if boundary_id is None:
+        if enforce_input.require_boundary:
+            return _deny(
+                enforce_input,
+                "boundary_required",
+                attempted_scope(enforce_input.action, enforce_input.resource),
+            )
+        return None
+
+    registry = enforce_input.boundary_registry
+    boundary = registry.get(boundary_id) if registry is not None else None
+    scope_attempted = attempted_scope(enforce_input.action, enforce_input.resource)
+    if boundary is None:
+        return _deny(
+            enforce_input,
+            "boundary_not_found",
+            scope_attempted,
+            attempted_boundary_id=boundary_id,
+        )
+    if boundary.workspace_id != enforce_input.grant.workspace_id:
+        return _deny(
+            enforce_input,
+            "boundary_wrong_workspace",
+            scope_attempted,
+            attempted_boundary_id=boundary_id,
+        )
+    if boundary.status != "active":
+        return _deny(
+            enforce_input,
+            "boundary_inactive",
+            scope_attempted,
+            boundary=boundary,
+            attempted_boundary_id=boundary_id,
+        )
+    return boundary
+
+
+def _deny(
+    enforce_input: EnforceInput,
+    reason: str,
+    scope_attempted: str,
+    *,
+    boundary: Boundary | None = None,
+    attempted_boundary_id: str | None = None,
+) -> DecisionResult:
+    grant = enforce_input.grant
+    return DecisionResult(
+        decision="deny",
+        reason=reason,
+        grant_id=grant.grant_id,
+        grant_ref=grant.grant_ref,
+        workspace_id=grant.workspace_id,
+        agent_id=grant.agent_id,
+        action=enforce_input.action,
+        resource=enforce_input.resource,
+        scope_attempted=scope_attempted,
+        scope_matched=None,
+        boundary=boundary,
+        attempted_boundary_id=attempted_boundary_id or enforce_input.boundary_id,
+    )

vinctor_core/infer.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from vinctor_core.scope import (
+    attempted_scope,
+    is_valid_grant_scope,
+    is_valid_requested_action,
+    is_valid_requested_resource,
+)
+
+
+@dataclass(frozen=True)
+class Observation:
+    """A single observed (action, resource) access, optionally pre-aggregated.
+
+    `count` is how many times it was seen; `last_seen` is an ISO-8601 timestamp
+    string (which sorts chronologically) or None.
+    """
+
+    action: str
+    resource: str
+    count: int = 1
+    last_seen: str | None = None
+
+
+@dataclass(frozen=True)
+class ScopeProposal:
+    """A proposed grant scope, annotated so an operator can review before applying.
+
+    `covers` lists the concrete `action:resource` scopes this proposal subsumes
+    (itself, for an exact scope; all observed siblings, for a generalized wildcard).
+    """
+
+    scope: str
+    count: int
+    last_seen: str | None
+    generalized: bool
+    covers: tuple[str, ...]
+
+
+def _latest(a: str | None, b: str | None) -> str | None:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return max(a, b)  # ISO-8601 strings sort chronologically
+
+
+def propose_scopes(
+    observations: Iterable[Observation],
+    *,
+    generalize: bool = False,
+) -> tuple[ScopeProposal, ...]:
+    """Deterministically propose the narrowest grant scopes covering observations.
+
+    Exact by default (one scope per distinct valid pair). With `generalize`, a group
+    of >=2 sibling resources under a parent of >=2 segments collapses to a single
+    terminal wildcard `action:parent/*`; shallow parents are deliberately NOT
+    widened (avoids top-level `category/*` footguns). Invalid actions/resources are
+    dropped. Propose-only — this never applies policy.
+    """
+    # Aggregate valid (action, resource) observations.
+    agg: dict[tuple[str, str], tuple[int, str | None]] = {}
+    for obs in observations:
+        if not is_valid_requested_action(obs.action):
+            continue
+        if not is_valid_requested_resource(obs.resource):
+            continue
+        key = (obs.action, obs.resource)
+        count, last_seen = agg.get(key, (0, None))
+        agg[key] = (count + obs.count, _latest(last_seen, obs.last_seen))
+
+    def _exact(action: str, resource: str, count: int, last_seen: str | None) -> ScopeProposal:
+        scope = attempted_scope(action, resource)
+        return ScopeProposal(
+            scope=scope,
+            count=count,
+            last_seen=last_seen,
+            generalized=False,
+            covers=(scope,),
+        )
+
+    if not generalize:
+        proposals = [
+            _exact(action, resource, count, last_seen)
+            for (action, resource), (count, last_seen) in agg.items()
+        ]
+        return tuple(sorted(proposals, key=lambda p: p.scope))
+
+    # Group by (action, parent) for generalization.
+    groups: dict[tuple[str, str], list[tuple[str, int, str | None]]] = defaultdict(list)
+    for (action, resource), (count, last_seen) in agg.items():
+        parent = resource.rsplit("/", 1)[0]
+        groups[(action, parent)].append((resource, count, last_seen))
+
+    proposals = []
+    for (action, parent), members in groups.items():
+        wildcard = f"{action}:{parent}/*"
+        deep_enough = len(parent.split("/")) >= 2
+        if len(members) >= 2 and deep_enough and is_valid_grant_scope(wildcard):
+            total = sum(count for _, count, _ in members)
+            latest: str | None = None
+            for _, _, last_seen in members:
+                latest = _latest(latest, last_seen)
+            covers = tuple(sorted(attempted_scope(action, resource) for resource, _, _ in members))
+            proposals.append(
+                ScopeProposal(
+                    scope=wildcard,
+                    count=total,
+                    last_seen=latest,
+                    generalized=True,
+                    covers=covers,
+                )
+            )
+        else:
+            proposals.extend(
+                _exact(action, resource, count, last_seen)
+                for resource, count, last_seen in members
+            )
+
+    return tuple(sorted(proposals, key=lambda p: p.scope))

vinctor_core/models.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal, Protocol
+
+Decision = Literal["permit", "deny"]
+BoundaryMode = Literal["fail_closed"]
+BoundaryStatus = Literal["active", "disabled"]
+
+
+@dataclass
+class Grant:
+    grant_id: str
+    grant_ref: str
+    workspace_id: str
+    agent_id: str
+    scopes: tuple[str, ...]
+    status: str
+    expires_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class Boundary:
+    boundary_id: str
+    workspace_id: str
+    name: str
+    runtime: str
+    boundary_type: str
+    mode: BoundaryMode
+    status: BoundaryStatus
+    created_at: datetime
+    updated_at: datetime
+
+    def with_status(self, status: BoundaryStatus, *, updated_at: datetime) -> Boundary:
+        return Boundary(
+            boundary_id=self.boundary_id,
+            workspace_id=self.workspace_id,
+            name=self.name,
+            runtime=self.runtime,
+            boundary_type=self.boundary_type,
+            mode=self.mode,
+            status=status,
+            created_at=self.created_at,
+            updated_at=updated_at,
+        )
+
+
+@dataclass(frozen=True)
+class BoundaryRegistrationInput:
+    workspace_id: str
+    name: str
+    runtime: str
+    boundary_type: str
+    mode: BoundaryMode = "fail_closed"
+    status: BoundaryStatus = "active"
+
+
+class BoundaryLookup(Protocol):
+    def get(self, boundary_id: str) -> Boundary | None: ...
+
+
+@dataclass(frozen=True)
+class EnforceInput:
+    grant: Grant
+    action: str
+    resource: str
+    now: datetime
+    boundary_id: str | None = None
+    boundary_registry: BoundaryLookup | None = None
+    require_boundary: bool = False
+
+
+@dataclass(frozen=True)
+class DecisionResult:
+    decision: Decision
+    reason: str
+    grant_id: str
+    grant_ref: str
+    workspace_id: str
+    agent_id: str
+    action: str
+    resource: str
+    scope_attempted: str
+    scope_matched: str | None
+    boundary: Boundary | None = None
+    attempted_boundary_id: str | None = None
+
+
+@dataclass(frozen=True)
+class PolicyInput:
+    workspace_id: str
+    agent_id: str
+    grants: tuple[Grant, ...]
+    action: str
+    resource: str
+    now: datetime
+    boundary_id: str | None = None
+    boundary_registry: BoundaryLookup | None = None
+
+
+@dataclass(frozen=True)
+class PolicyResult:
+    decision: Decision
+    reason: str
+    workspace_id: str
+    agent_id: str
+    action: str
+    resource: str
+    scope_attempted: str
+    scope_matched: str | None
+    grant_id: str | None = None
+    grant_ref: str | None = None
+    enforce_result: DecisionResult | None = None
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    event_id: str
+    event_type: str
+    decision: Decision
+    reason: str
+    workspace_id: str
+    agent_id: str
+    grant_id: str
+    grant_ref: str
+    action: str
+    resource: str
+    scope_attempted: str
+    scope_matched: str | None
+    boundary_id: str | None
+    runtime: str | None
+    boundary_type: str | None
+    created_at: datetime
+    enforcing_principal: str | None = None
+    # Pre-grant-evaluation rejection fields (ADR 0008). Absent on decision and
+    # grant-lifecycle events; set only on operator-only rejection events.
+    reason_code: str | None = None
+    occurrence_count: int | None = None
+    first_seen_at: datetime | None = None
+    last_seen_at: datetime | None = None
+    # ADR 0007 Model 2 identity-proof (set only on a proven delegated decision).
+    identity_proven: bool = False
+    token_id: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        event: dict[str, object] = {
+            "event_id": self.event_id,
+            "event_type": self.event_type,
+            "decision": self.decision,
+            "reason": self.reason,
+            "workspace_id": self.workspace_id,
+            "agent_id": self.agent_id,
+            "grant_id": self.grant_id,
+            "grant_ref": self.grant_ref,
+            "action": self.action,
+            "resource": self.resource,
+            "scope_attempted": self.scope_attempted,
+            "scope_matched": self.scope_matched,
+            "boundary_id": self.boundary_id,
+            "runtime": self.runtime,
+            "boundary_type": self.boundary_type,
+            "created_at": self.created_at.isoformat(),
+        }
+        if self.enforcing_principal is not None:
+            event["enforcing_principal"] = self.enforcing_principal
+        if self.reason_code is not None:
+            event["reason_code"] = self.reason_code
+        if self.occurrence_count is not None:
+            event["occurrence_count"] = self.occurrence_count
+        if self.first_seen_at is not None:
+            event["first_seen_at"] = self.first_seen_at.isoformat()
+        if self.last_seen_at is not None:
+            event["last_seen_at"] = self.last_seen_at.isoformat()
+        if self.identity_proven:
+            event["identity_proven"] = True
+        if self.token_id is not None:
+            event["token_id"] = self.token_id
+        return event

vinctor_core/policy.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from vinctor_core.enforce import evaluate_enforce
+from vinctor_core.models import DecisionResult, EnforceInput, Grant, PolicyInput, PolicyResult
+from vinctor_core.scope import (
+    attempted_scope,
+    is_valid_requested_action,
+    is_valid_requested_resource,
+)
+
+
+def evaluate_policy(policy_input: PolicyInput) -> PolicyResult:
+    scope_attempted = attempted_scope(policy_input.action, policy_input.resource)
+
+    if not is_valid_requested_action(policy_input.action):
+        return _deny(policy_input, "invalid_action", scope_attempted)
+    if not is_valid_requested_resource(policy_input.resource):
+        return _deny(policy_input, "invalid_resource", scope_attempted)
+
+    for grant in _candidate_grants(policy_input):
+        result = evaluate_enforce(
+            EnforceInput(
+                grant=grant,
+                action=policy_input.action,
+                resource=policy_input.resource,
+                now=policy_input.now,
+                boundary_id=policy_input.boundary_id,
+                boundary_registry=policy_input.boundary_registry,
+            )
+        )
+        if result.decision == "permit":
+            return _from_enforce_result(policy_input, result)
+        if result.reason.startswith("boundary_"):
+            return _from_enforce_result(policy_input, result)
+        if result.reason in {
+            "invalid_action",
+            "invalid_resource",
+            "invalid_grant_scope",
+        }:
+            return _from_enforce_result(policy_input, result)
+
+    return _deny(policy_input, "no_applicable_grant", scope_attempted)
+
+
+def _candidate_grants(policy_input: PolicyInput) -> Iterator[Grant]:
+    return (
+        grant
+        for grant in policy_input.grants
+        if grant.workspace_id == policy_input.workspace_id
+        and grant.agent_id == policy_input.agent_id
+    )
+
+
+def _from_enforce_result(
+    policy_input: PolicyInput,
+    result: DecisionResult,
+) -> PolicyResult:
+    return PolicyResult(
+        decision=result.decision,
+        reason=result.reason,
+        workspace_id=policy_input.workspace_id,
+        agent_id=policy_input.agent_id,
+        action=policy_input.action,
+        resource=policy_input.resource,
+        scope_attempted=result.scope_attempted,
+        scope_matched=result.scope_matched,
+        grant_id=result.grant_id,
+        grant_ref=result.grant_ref,
+        enforce_result=result,
+    )
+
+
+def _deny(
+    policy_input: PolicyInput,
+    reason: str,
+    scope_attempted: str,
+) -> PolicyResult:
+    return PolicyResult(
+        decision="deny",
+        reason=reason,
+        workspace_id=policy_input.workspace_id,
+        agent_id=policy_input.agent_id,
+        action=policy_input.action,
+        resource=policy_input.resource,
+        scope_attempted=scope_attempted,
+        scope_matched=None,
+    )

vinctor_core/py.typed

@@ -0,0 +1 @@
+