arrow-local-uri 0.1.0__tar.gz

arrow_local_uri-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: arrow-local-uri
+Version: 0.1.0
+Summary: Local URI trust, authentication, validity, tracing, and elevation framework.
+Author: Joao Lopes
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10
+
+# Arrow
+
+Arrow is an independent local URI trust boundary for Python applications. It
+provides signed and expiring envelopes, authentication strength, provenance,
+capabilities, validity, replay protection, revocation, delegation, tracing,
+redaction, rate limiting, idempotency, OAuth primitives, and native OS
+privilege elevation.
+
+Arrow contains no Lake Terminal storage or session-management logic.
+
+<!-- exactus:inventory:start -->
+## Directory contents
+
+### Files
+
+- [`pyproject.toml`](pyproject.toml) — Provide pyproject toml content.
+
+### Subdirectories
+
+- [`arrow_uri/`](arrow_uri/README.md) — Arrow public interface.
+
+<!-- exactus:inventory:end -->

arrow_local_uri-0.1.0/README.md

@@ -0,0 +1,22 @@
+# Arrow
+
+Arrow is an independent local URI trust boundary for Python applications. It
+provides signed and expiring envelopes, authentication strength, provenance,
+capabilities, validity, replay protection, revocation, delegation, tracing,
+redaction, rate limiting, idempotency, OAuth primitives, and native OS
+privilege elevation.
+
+Arrow contains no Lake Terminal storage or session-management logic.
+
+<!-- exactus:inventory:start -->
+## Directory contents
+
+### Files
+
+- [`pyproject.toml`](pyproject.toml) — Provide pyproject toml content.
+
+### Subdirectories
+
+- [`arrow_uri/`](arrow_uri/README.md) — Arrow public interface.
+
+<!-- exactus:inventory:end -->

arrow_local_uri-0.1.0/arrow_local_uri.egg-info/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: arrow-local-uri
+Version: 0.1.0
+Summary: Local URI trust, authentication, validity, tracing, and elevation framework.
+Author: Joao Lopes
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10
+
+# Arrow
+
+Arrow is an independent local URI trust boundary for Python applications. It
+provides signed and expiring envelopes, authentication strength, provenance,
+capabilities, validity, replay protection, revocation, delegation, tracing,
+redaction, rate limiting, idempotency, OAuth primitives, and native OS
+privilege elevation.
+
+Arrow contains no Lake Terminal storage or session-management logic.
+
+<!-- exactus:inventory:start -->
+## Directory contents
+
+### Files
+
+- [`pyproject.toml`](pyproject.toml) — Provide pyproject toml content.
+
+### Subdirectories
+
+- [`arrow_uri/`](arrow_uri/README.md) — Arrow public interface.
+
+<!-- exactus:inventory:end -->

arrow_local_uri-0.1.0/arrow_local_uri.egg-info/SOURCES.txt

@@ -0,0 +1,29 @@
+README.md
+pyproject.toml
+arrow_local_uri.egg-info/PKG-INFO
+arrow_local_uri.egg-info/SOURCES.txt
+arrow_local_uri.egg-info/dependency_links.txt
+arrow_local_uri.egg-info/requires.txt
+arrow_local_uri.egg-info/top_level.txt
+arrow_uri/__init__.py
+arrow_uri/audit.py
+arrow_uri/context.py
+arrow_uri/delegation.py
+arrow_uri/elevation.py
+arrow_uri/elevation_uri.py
+arrow_uri/envelope.py
+arrow_uri/errors.py
+arrow_uri/helper.py
+arrow_uri/identity.py
+arrow_uri/json_types.py
+arrow_uri/keys.py
+arrow_uri/models.py
+arrow_uri/oauth.py
+arrow_uri/protection.py
+arrow_uri/revocation.py
+arrow_uri/secrets.py
+arrow_uri/security.py
+arrow_uri/trace.py
+arrow_uri/trust.py
+arrow_uri/uri.py
+arrow_uri/validity.py

arrow_local_uri-0.1.0/arrow_local_uri.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

arrow_local_uri-0.1.0/arrow_local_uri.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=2.10

arrow_local_uri-0.1.0/arrow_local_uri.egg-info/top_level.txt

@@ -0,0 +1 @@
+arrow_uri

arrow_local_uri-0.1.0/arrow_uri/__init__.py

@@ -0,0 +1,133 @@
+"""Arrow public interface."""
+
+from .audit import AuditEvent, AuditRecord, HashChainAuditLog
+from .context import Deadline, RequestContext, RequestIdentity
+from .delegation import Delegation, DelegationManager, DelegationRequest
+from .elevation import ElevationGrant, PrivilegeBroker
+from .elevation_uri import (
+    ElevationEnvelope,
+    ElevationURIManager,
+    PrivilegedOperation,
+    PrivilegedRegistry,
+)
+from .envelope import EnvelopeSigner, SignedEnvelope
+from .helper import HelperGrant, HelperGrantSigner
+from .identity import ExecutablePolicy, PeerIdentityProvider
+from .keys import KeyRing, KeyStatus, SigningKey
+from .models import (
+    CallerInfo,
+    SecurityContext,
+    TraceContext,
+    URIRequest,
+    URIResponse,
+    URIStatus,
+)
+from .oauth import (
+    AuthorizationRequest,
+    DeviceAuthorization,
+    OAuthClient,
+    OAuthTransport,
+    PKCEPair,
+    TokenSet,
+)
+from .protection import IdempotencyStore, RateLimiter, Redactor
+from .revocation import RevocationRegistry
+from .secrets import MemorySecretStore, RefreshTokenVault, SecretStore
+from .security import (
+    AuthorizationPolicy,
+    NonceStore,
+    OAuthToken,
+    OAuthTokenValidator,
+    SessionClaims,
+    SignedSessionManager,
+    StaticOAuthValidator,
+)
+from .trace import Span, SpanStatus, Trace
+from .trust import (
+    AuthenticationStrength,
+    Evidence,
+    EvidenceKind,
+    Principal,
+    TrustLevel,
+)
+from .uri import (
+    SignedURIManager,
+    SignedURIRequest,
+    URIValue,
+    URIValues,
+)
+from .validity import (
+    ValidityCode,
+    ValidityPolicy,
+    ValidityResult,
+    ValidityWindow,
+)
+
+__all__: tuple[str, ...] = (
+    "AuditEvent",
+    "AuditRecord",
+    "AuthenticationStrength",
+    "AuthorizationPolicy",
+    "AuthorizationRequest",
+    "CallerInfo",
+    "Deadline",
+    "Delegation",
+    "DelegationManager",
+    "DelegationRequest",
+    "DeviceAuthorization",
+    "ElevationEnvelope",
+    "ElevationGrant",
+    "ElevationURIManager",
+    "EnvelopeSigner",
+    "Evidence",
+    "EvidenceKind",
+    "ExecutablePolicy",
+    "HashChainAuditLog",
+    "HelperGrant",
+    "HelperGrantSigner",
+    "IdempotencyStore",
+    "KeyRing",
+    "KeyStatus",
+    "MemorySecretStore",
+    "NonceStore",
+    "OAuthClient",
+    "OAuthToken",
+    "OAuthTokenValidator",
+    "OAuthTransport",
+    "PKCEPair",
+    "PeerIdentityProvider",
+    "Principal",
+    "PrivilegeBroker",
+    "PrivilegedOperation",
+    "PrivilegedRegistry",
+    "RateLimiter",
+    "Redactor",
+    "RefreshTokenVault",
+    "RequestContext",
+    "RequestIdentity",
+    "RevocationRegistry",
+    "SecretStore",
+    "SecurityContext",
+    "SessionClaims",
+    "SignedEnvelope",
+    "SignedSessionManager",
+    "SignedURIManager",
+    "SignedURIRequest",
+    "SigningKey",
+    "Span",
+    "SpanStatus",
+    "StaticOAuthValidator",
+    "TokenSet",
+    "Trace",
+    "TraceContext",
+    "TrustLevel",
+    "URIRequest",
+    "URIResponse",
+    "URIStatus",
+    "URIValue",
+    "URIValues",
+    "ValidityCode",
+    "ValidityPolicy",
+    "ValidityResult",
+    "ValidityWindow",
+)

arrow_local_uri-0.1.0/arrow_uri/audit.py

@@ -0,0 +1,128 @@
+"""Tamper-evident hash-chained audit records."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from hashlib import sha256
+from json import dumps
+from threading import Lock
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AuditEvent:
+    """Fields describing one audited event.
+
+    Attributes:
+        timestamp: Event timestamp text.
+        request_id: Originating request identifier.
+        trace_id: Originating trace identifier.
+        principal: Acting principal, when known.
+        action: Performed action.
+        outcome: Event outcome.
+
+    """
+
+    timestamp: str
+    request_id: str
+    trace_id: str
+    principal: str | None
+    action: str
+    outcome: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AuditRecord:
+    """One chained audit record.
+
+    Attributes:
+        sequence: Monotonic record sequence.
+        timestamp: Event timestamp text.
+        request_id: Originating request identifier.
+        trace_id: Originating trace identifier.
+        principal: Acting principal, when known.
+        action: Performed action.
+        outcome: Event outcome.
+        previous_hash: Hash of the preceding record.
+        record_hash: Hash of this record.
+
+    """
+
+    sequence: int
+    timestamp: str
+    request_id: str
+    trace_id: str
+    principal: str | None
+    action: str
+    outcome: str
+    previous_hash: str
+    record_hash: str
+
+
+class HashChainAuditLog:
+    """Append-only audit log with SHA-256 chain integrity."""
+
+    def __init__(self, *, path: Path) -> None:
+        """Create a log writing chained records to a JSONL file.
+
+        Args:
+            path: Destination JSONL file path.
+
+        """
+        self._path: Path = path
+        self._lock: Lock = Lock()
+        self._sequence: int = 0
+        self._previous_hash: str = "0" * 64
+
+    def append(self, *, event: AuditEvent) -> AuditRecord:
+        """Append and return a chained record.
+
+        Args:
+            event: Audited event fields.
+
+        Returns:
+            The appended chained record.
+
+        """
+        with self._lock:
+            sequence: int = self._sequence + 1
+            material: str = dumps(
+                obj={
+                    "sequence": sequence,
+                    "timestamp": event.timestamp,
+                    "request_id": event.request_id,
+                    "trace_id": event.trace_id,
+                    "principal": event.principal,
+                    "action": event.action,
+                    "outcome": event.outcome,
+                    "previous_hash": self._previous_hash,
+                },
+                separators=(",", ":"),
+                sort_keys=True,
+            )
+            digest: str = sha256(
+                data=material.encode(encoding="utf-8"),
+            ).hexdigest()
+            record: AuditRecord = AuditRecord(
+                sequence=sequence,
+                timestamp=event.timestamp,
+                request_id=event.request_id,
+                trace_id=event.trace_id,
+                principal=event.principal,
+                action=event.action,
+                outcome=event.outcome,
+                previous_hash=self._previous_hash,
+                record_hash=digest,
+            )
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open(mode="a", encoding="utf-8") as stream:
+                _ = stream.write(
+                    dumps(obj=asdict(obj=record), separators=(",", ":"))
+                    + "\n",
+                )
+            self._sequence = sequence
+            self._previous_hash = digest
+            return record

arrow_local_uri-0.1.0/arrow_uri/context.py

@@ -0,0 +1,87 @@
+"""Immutable trusted request context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import CallerInfo, SecurityContext
+    from .trace import Trace
+    from .trust import Principal
+    from .validity import ValidityResult
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Deadline:
+    """Absolute request deadline.
+
+    Attributes:
+        at: Instant at which the deadline elapses.
+
+    """
+
+    at: datetime
+
+    @property
+    def expired(self) -> bool:
+        """Return whether the deadline has elapsed.
+
+        Returns:
+            Whether the current time is at or past the deadline.
+
+        """
+        return datetime.now(tz=UTC) >= self.at
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RequestIdentity:
+    """Stable identity for one invocation.
+
+    Attributes:
+        request_id: Unique request identifier.
+        operation: Requested operation name.
+        uri: Source request URI.
+
+    """
+
+    request_id: str
+    operation: str
+    uri: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RequestContext:
+    """Trusted context delivered to application code.
+
+    Attributes:
+        request: Stable request identity.
+        caller: Transport-established caller provenance.
+        principal: Consolidated authenticated principal.
+        security: Authenticated identity and authorization state.
+        validity: Validity evaluation result.
+        trace: Trace collector for the request.
+        deadline: Optional absolute request deadline.
+
+    """
+
+    request: RequestIdentity
+    caller: CallerInfo
+    principal: Principal
+    security: SecurityContext
+    validity: ValidityResult
+    trace: Trace
+    deadline: Deadline | None = None
+
+    @property
+    def executable(self) -> bool:
+        """Return whether validity and deadline permit execution.
+
+        Returns:
+            Whether the request may execute right now.
+
+        """
+        return self.validity.valid and (
+            self.deadline is None or not self.deadline.expired
+        )

arrow_local_uri-0.1.0/arrow_uri/delegation.py

@@ -0,0 +1,141 @@
+"""Capability delegation for local agents and applications."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from secrets import token_urlsafe
+from typing import TYPE_CHECKING
+
+from .errors import AuthorizationError
+
+if TYPE_CHECKING:
+    from .revocation import RevocationRegistry
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Delegation:
+    """Temporary subset of a principal's capabilities.
+
+    Attributes:
+        delegation_id: Unique delegation identifier.
+        issuer: Issuing principal.
+        subject: Delegated subject.
+        capabilities: Delegated capability names.
+        issued_at: Issue timestamp.
+        expires_at: Expiry timestamp.
+        depth: Chain depth of this delegation.
+        max_depth: Maximum permitted chain depth.
+
+    """
+
+    delegation_id: str
+    issuer: str
+    subject: str
+    capabilities: frozenset[str]
+    issued_at: datetime
+    expires_at: datetime
+    depth: int
+    max_depth: int
+
+    @property
+    def valid(self) -> bool:
+        """Return whether the delegation remains temporally valid.
+
+        Returns:
+            Whether the expiry timestamp is still in the future.
+
+        """
+        return datetime.now(tz=UTC) < self.expires_at
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DelegationRequest:
+    """Fields describing one requested delegation.
+
+    Attributes:
+        issuer: Issuing principal.
+        subject: Delegated subject.
+        issuer_capabilities: Capabilities the issuer holds.
+        capabilities: Capabilities to delegate.
+        ttl: Delegation lifetime.
+        depth: Chain depth of this delegation.
+        max_depth: Maximum permitted chain depth.
+
+    """
+
+    issuer: str
+    subject: str
+    issuer_capabilities: frozenset[str]
+    capabilities: frozenset[str]
+    ttl: timedelta
+    depth: int = 0
+    max_depth: int = 1
+
+
+@dataclass(slots=True, kw_only=True)
+class DelegationManager:
+    """Issue constrained delegation chains.
+
+    Attributes:
+        revocations: Revocation registry consulted during validation.
+
+    """
+
+    revocations: RevocationRegistry
+
+    @staticmethod
+    def issue(*, request: DelegationRequest) -> Delegation:
+        """Issue a subset-only delegation.
+
+        Args:
+            request: Requested delegation fields.
+
+        Returns:
+            The issued delegation.
+
+        Raises:
+            AuthorizationError: When the request exceeds the issuer's
+                capabilities or the permitted chain depth.
+
+        """
+        if not request.capabilities <= request.issuer_capabilities:
+            msg: str = (
+                "Cannot delegate capabilities the issuer does not possess."
+            )
+            raise AuthorizationError(
+                msg,
+            )
+        if request.depth > request.max_depth:
+            msg = "Delegation depth exceeded."
+            raise AuthorizationError(msg)
+        now: datetime = datetime.now(tz=UTC)
+        return Delegation(
+            delegation_id=token_urlsafe(nbytes=18),
+            issuer=request.issuer,
+            subject=request.subject,
+            capabilities=request.capabilities,
+            issued_at=now,
+            expires_at=now + request.ttl,
+            depth=request.depth,
+            max_depth=request.max_depth,
+        )
+
+    def validate(self, *, delegation: Delegation) -> None:
+        """Validate expiry and revocation.
+
+        Args:
+            delegation: Delegation to validate.
+
+        Raises:
+            AuthorizationError: When the delegation is expired or revoked.
+
+        """
+        if not delegation.valid:
+            msg: str = "Delegation expired."
+            raise AuthorizationError(msg)
+        if self.revocations.is_revoked(
+            identifier=delegation.delegation_id,
+        ):
+            msg = "Delegation revoked."
+            raise AuthorizationError(msg)