auths-python 0.1.0__cp38-abi3-win_amd64.whl

auths/jwt.py

@@ -0,0 +1,253 @@
+"""JWT validation for Auths OIDC tokens.
+
+Requires PyJWT: pip install auths-python[jwt]
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger("auths.jwt")
+
+
+@dataclass
+class AuthsClaims:
+    """Validated claims from an Auths OIDC token."""
+
+    sub: str
+    """Subject claim — the signer's DID."""
+    keri_prefix: str
+    """KERI prefix of the identity."""
+    capabilities: list[str]
+    """Capabilities granted by this token."""
+    iss: str
+    """Issuer claim — the OIDC bridge URL."""
+    aud: str
+    """Audience claim — the service this token is intended for."""
+    exp: int
+    """Expiration time as Unix timestamp."""
+    iat: int
+    """Issued-at time as Unix timestamp."""
+    jti: str
+    """Unique JWT ID for replay prevention."""
+    signer_type: str | None = None
+    """Signer classification: `"Human"`, `"Agent"`, or `"Workload"`."""
+    delegated_by: str | None = None
+    """DID of the delegating identity, if this is a delegated token."""
+    witness_quorum: dict | None = None
+    """Witness quorum metadata, if witness-backed."""
+    github_actor: str | None = None
+    """GitHub username, present for GitHub Actions OIDC tokens."""
+    github_repository: str | None = None
+    """GitHub repository (owner/repo), present for GitHub Actions OIDC tokens."""
+
+    def has_capability(self, cap: str) -> bool:
+        """Check if token grants a specific capability."""
+        return cap in self.capabilities
+
+    def has_any_capability(self, caps: list[str]) -> bool:
+        """Check if token grants any of the listed capabilities."""
+        return any(c in self.capabilities for c in caps)
+
+    def has_all_capabilities(self, caps: list[str]) -> bool:
+        """Check if token grants all of the listed capabilities."""
+        return all(c in self.capabilities for c in caps)
+
+    @property
+    def is_agent(self) -> bool:
+        return self.signer_type == "Agent"
+
+    @property
+    def is_human(self) -> bool:
+        return self.signer_type == "Human"
+
+    @property
+    def is_delegated(self) -> bool:
+        return self.delegated_by is not None
+
+    def __repr__(self) -> str:
+        caps = ", ".join(self.capabilities[:3])
+        if len(self.capabilities) > 3:
+            caps += f" +{len(self.capabilities) - 3}"
+        sub_short = self.sub[:25] if len(self.sub) > 25 else self.sub
+        return (
+            f"AuthsClaims(sub='{sub_short}...', "
+            f"caps=[{caps}], type={self.signer_type})"
+        )
+
+
+class AuthsJWKSClient:
+    """JWKS client with automatic key caching for Auths OIDC token validation.
+
+    Args:
+        jwks_url: The OIDC bridge's JWKS endpoint.
+        cache_ttl: How long to cache JWKS keys, in seconds (default: 300).
+
+    Examples:
+        ```python
+        jwks = AuthsJWKSClient("https://bridge.example.com/.well-known/jwks.json")
+        claims = jwks.verify_token(token, audience="my-service")
+        ```
+    """
+
+    def __init__(self, jwks_url: str, *, cache_ttl: int = 300):
+        try:
+            import jwt as pyjwt
+            from jwt import PyJWKClient
+        except ImportError:
+            raise ImportError(
+                "PyJWT is required for JWT validation. "
+                "Install it with: pip install auths-python[jwt]"
+            )
+
+        from auths._errors import NetworkError
+
+        self._pyjwt = pyjwt
+        self._NetworkError = NetworkError
+        self._client = PyJWKClient(jwks_url, cache_jwk_set=True, lifespan=cache_ttl)
+        self._jwks_url = jwks_url
+        logger.debug("Initialized JWKS client for %s (cache_ttl=%ds)", jwks_url, cache_ttl)
+
+    def verify_token(
+        self,
+        token: str,
+        *,
+        audience: str,
+        issuer: str | None = None,
+        leeway: int = 60,
+    ) -> AuthsClaims:
+        """Verify an Auths OIDC token and extract claims.
+
+        Args:
+            token: Raw JWT bearer token string.
+            audience: Expected audience claim.
+            issuer: Expected issuer claim (optional, verified if set).
+            leeway: Clock skew tolerance in seconds (default: 60).
+
+        Returns:
+            AuthsClaims with the validated token claims.
+
+        Raises:
+            VerificationError: If the token is expired, has wrong audience/issuer, or invalid signature.
+            NetworkError: If JWKS keys cannot be fetched.
+
+        Examples:
+            ```python
+            claims = jwks.verify_token(bearer_token, audience="my-service")
+            if claims.has_capability("read"):
+                allow_access()
+            ```
+        """
+        from auths._errors import VerificationError
+
+        try:
+            signing_key = self._client.get_signing_key_from_jwt(token)
+        except Exception as e:
+            logger.warning("JWKS fetch failed for %s: %s", self._jwks_url, e)
+            raise self._NetworkError(
+                f"Failed to fetch JWKS from {self._jwks_url}: {e}",
+                code="jwks_fetch_failed",
+                should_retry=True,
+            )
+
+        try:
+            options = {"verify_aud": True, "verify_exp": True}
+            if issuer:
+                options["verify_iss"] = True
+
+            decoded = self._pyjwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256", "ES256", "EdDSA"],
+                audience=audience,
+                issuer=issuer,
+                leeway=leeway,
+                options=options,
+            )
+        except self._pyjwt.ExpiredSignatureError:
+            raise VerificationError(
+                "Token expired. Request a new token from the OIDC bridge.",
+                code="token_expired",
+            )
+        except self._pyjwt.InvalidAudienceError:
+            raise VerificationError(
+                f"Token audience does not match expected '{audience}'. "
+                "Ensure the token was issued for this service.",
+                code="invalid_audience",
+            )
+        except self._pyjwt.InvalidIssuerError:
+            raise VerificationError(
+                f"Token issuer does not match expected '{issuer}'. "
+                "Check the OIDC bridge URL configuration.",
+                code="invalid_issuer",
+            )
+        except self._pyjwt.InvalidSignatureError:
+            raise VerificationError(
+                "Token signature is invalid. The token may have been tampered with "
+                "or the JWKS keys may have rotated. Try refreshing the JWKS cache.",
+                code="invalid_signature",
+            )
+        except self._pyjwt.DecodeError as e:
+            raise VerificationError(
+                f"Token decode failed: {e}. Ensure the token is a valid JWT string.",
+                code="decode_error",
+            )
+
+        logger.debug(
+            "Token verified: sub=%s, caps=%s",
+            decoded.get("sub"),
+            decoded.get("capabilities"),
+        )
+
+        return AuthsClaims(
+            sub=decoded["sub"],
+            keri_prefix=decoded.get("keri_prefix", ""),
+            capabilities=decoded.get("capabilities", []),
+            iss=decoded.get("iss", ""),
+            aud=decoded.get("aud", ""),
+            exp=decoded.get("exp", 0),
+            iat=decoded.get("iat", 0),
+            jti=decoded.get("jti", ""),
+            signer_type=decoded.get("signer_type"),
+            delegated_by=decoded.get("delegated_by"),
+            witness_quorum=decoded.get("witness_quorum"),
+            github_actor=decoded.get("github_actor"),
+            github_repository=decoded.get("github_repository"),
+        )
+
+
+def verify_token(
+    token: str,
+    *,
+    jwks_url: str,
+    audience: str,
+    issuer: str | None = None,
+    leeway: int = 60,
+) -> AuthsClaims:
+    """Verify an Auths OIDC token (one-shot, no JWKS caching).
+
+    For production use, prefer `AuthsJWKSClient` which caches JWKS keys.
+
+    Args:
+        token: Raw JWT bearer token string.
+        jwks_url: URL to fetch JSON Web Key Set.
+        audience: Expected audience claim.
+        issuer: Expected issuer claim (optional).
+        leeway: Clock skew tolerance in seconds (default: 60).
+
+    Returns:
+        AuthsClaims with the validated token claims.
+
+    Raises:
+        VerificationError: If the token is invalid.
+        NetworkError: If JWKS keys cannot be fetched.
+
+    Examples:
+        ```python
+        from auths.jwt import verify_token
+        claims = verify_token(token, jwks_url="...", audience="my-service")
+        ```
+    """
+    client = AuthsJWKSClient(jwks_url)
+    return client.verify_token(token, audience=audience, issuer=issuer, leeway=leeway)

auths/org.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+from auths._native import (
+    add_org_member as _add_org_member,
+    create_org as _create_org,
+    list_org_members as _list_org_members,
+    revoke_org_member as _revoke_org_member,
+)
+from auths._client import _map_error
+from auths._errors import OrgError
+
+
+@dataclass
+class Org:
+    """An organization identity."""
+
+    prefix: str
+    """KERI prefix of the organization identity."""
+    did: str
+    """The organization's DID (`did:keri:...`)."""
+    label: str
+    """Human-readable organization name."""
+    repo_path: str
+    """Path to the identity repository."""
+
+    def __repr__(self):
+        return f"Org(did={self.did!r}, label={self.label!r})"
+
+
+@dataclass
+class OrgMember:
+    """A member within an organization."""
+
+    member_did: str
+    """DID of the member."""
+    role: str
+    """Member role: `"admin"`, `"member"`, or `"readonly"`."""
+    capabilities: list[str]
+    """Capabilities granted to this member."""
+    issuer_did: str
+    """DID of the identity that issued the membership attestation."""
+    attestation_rid: str
+    """RID of the membership attestation."""
+    revoked: bool
+    """Whether this membership has been revoked."""
+    expires_at: Optional[str]
+    """ISO 8601 expiry timestamp, or None for non-expiring memberships."""
+
+    @property
+    def is_admin(self) -> bool:
+        """Whether this member has admin role."""
+        return self.role == "admin"
+
+    def __repr__(self):
+        status = " revoked" if self.revoked else ""
+        return f"OrgMember(did={self.member_did!r}, role={self.role!r}{status})"
+
+
+class OrgService:
+    """Resource service for organization operations."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        label: str,
+        repo_path: str | None = None,
+        passphrase: str | None = None,
+    ) -> Org:
+        """Create a new organization identity.
+
+        Args:
+            label: Human-readable name for the org.
+            repo_path: Override identity store path.
+            passphrase: Override passphrase.
+
+        Returns:
+            Org with the KERI prefix, DID, and label.
+
+        Raises:
+            OrgError: If organization creation fails.
+            KeychainError: If the keychain is locked or inaccessible.
+
+        Examples:
+            ```python
+            org = client.orgs.create("my-team")
+            ```
+        """
+        rp = repo_path or self._client.repo_path
+        pp = passphrase or self._client._passphrase
+        try:
+            prefix, did, lbl, rpath = _create_org(label, rp, pp)
+            return Org(prefix=prefix, did=did, label=lbl, repo_path=rpath)
+        except (ValueError, RuntimeError) as exc:
+            raise _map_error(exc, default_cls=OrgError) from exc
+
+    def add_member(
+        self,
+        org_did: str,
+        member_did: str,
+        role: str = "member",
+        capabilities: list[str] | None = None,
+        note: str | None = None,
+        repo_path: str | None = None,
+        passphrase: str | None = None,
+        member_public_key_hex: str | None = None,
+    ) -> OrgMember:
+        """Add a member to an organization.
+
+        Args:
+            org_did: The organization's DID (`did:keri:...`).
+            member_did: The member's DID to add.
+            role: One of `"admin"`, `"member"`, `"readonly"`.
+            capabilities: Explicit capability list. If None, uses role defaults.
+            note: Optional human-readable note for the attestation.
+            member_public_key_hex: Member's Ed25519 public key hex. Required when
+                the member's identity is in a different registry.
+
+        Returns:
+            OrgMember with the membership attestation details.
+
+        Raises:
+            OrgError: If the member cannot be added.
+
+        Examples:
+            ```python
+            member = client.orgs.add_member(org.did, dev.did, role="member")
+            ```
+        """
+        rp = repo_path or self._client.repo_path
+        pp = passphrase or self._client._passphrase
+        caps_json = json.dumps(capabilities) if capabilities else None
+        try:
+            m_did, r, caps_str, issuer, rid, revoked, expires = _add_org_member(
+                org_did, member_did, role, rp, caps_json, pp, note,
+                member_public_key_hex,
+            )
+            return OrgMember(
+                member_did=m_did,
+                role=r,
+                capabilities=json.loads(caps_str) if caps_str else [],
+                issuer_did=issuer,
+                attestation_rid=rid,
+                revoked=revoked,
+                expires_at=expires,
+            )
+        except (ValueError, RuntimeError) as exc:
+            raise _map_error(exc, default_cls=OrgError) from exc
+
+    def revoke_member(
+        self,
+        org_did: str,
+        member_did: str,
+        note: str | None = None,
+        repo_path: str | None = None,
+        passphrase: str | None = None,
+        member_public_key_hex: str | None = None,
+    ) -> OrgMember:
+        """Revoke a member's authorization.
+
+        Args:
+            org_did: The organization's DID.
+            member_did: The member's DID to revoke.
+            note: Optional human-readable note.
+            member_public_key_hex: Member's Ed25519 public key hex. Required when
+                the member's identity is in a different registry.
+
+        Returns:
+            OrgMember with revoked status.
+
+        Raises:
+            OrgError: If the member cannot be revoked.
+
+        Examples:
+            ```python
+            revoked = client.orgs.revoke_member(org.did, dev.did)
+            ```
+        """
+        rp = repo_path or self._client.repo_path
+        pp = passphrase or self._client._passphrase
+        try:
+            m_did, r, caps_str, issuer, rid, revoked, expires = _revoke_org_member(
+                org_did, member_did, rp, pp, note, member_public_key_hex,
+            )
+            return OrgMember(
+                member_did=m_did,
+                role=r,
+                capabilities=json.loads(caps_str) if caps_str else [],
+                issuer_did=issuer,
+                attestation_rid=rid,
+                revoked=revoked,
+                expires_at=expires,
+            )
+        except (ValueError, RuntimeError) as exc:
+            raise _map_error(exc, default_cls=OrgError) from exc
+
+    def update_member(
+        self,
+        org_did: str,
+        member_did: str,
+        role: str | None = None,
+        capabilities: list[str] | None = None,
+        note: str | None = None,
+        repo_path: str | None = None,
+        passphrase: str | None = None,
+        member_public_key_hex: str | None = None,
+    ) -> OrgMember:
+        """Update a member's role or capabilities.
+
+        Args:
+            org_did: The organization's DID.
+            member_did: The member's DID to update.
+            role: New role. If None, keeps current.
+            capabilities: New capabilities. If None, uses role defaults.
+            note: Optional note.
+            member_public_key_hex: Member's Ed25519 public key hex. Required when
+                the member's identity is in a different registry.
+
+        Returns:
+            OrgMember with the updated role and capabilities.
+
+        Raises:
+            OrgError: If the member cannot be updated.
+
+        Examples:
+            ```python
+            updated = client.orgs.update_member(org.did, dev.did, role="admin")
+            ```
+        """
+        self.revoke_member(
+            org_did, member_did, note="superseded by update",
+            repo_path=repo_path, passphrase=passphrase,
+            member_public_key_hex=member_public_key_hex,
+        )
+        return self.add_member(
+            org_did, member_did, role=role or "member",
+            capabilities=capabilities, note=note,
+            repo_path=repo_path, passphrase=passphrase,
+            member_public_key_hex=member_public_key_hex,
+        )
+
+    def list_members(
+        self,
+        org_did: str,
+        include_revoked: bool = False,
+        repo_path: str | None = None,
+    ) -> list[OrgMember]:
+        """List all members of an organization.
+
+        Args:
+            org_did: The organization's DID.
+            include_revoked: If True, includes revoked members.
+
+        Returns:
+            List of OrgMember objects.
+
+        Raises:
+            OrgError: If the organization doesn't exist.
+
+        Examples:
+            ```python
+            members = client.orgs.list_members(org.did)
+            ```
+        """
+        rp = repo_path or self._client.repo_path
+        try:
+            members_json = _list_org_members(org_did, include_revoked, rp)
+            raw = json.loads(members_json)
+            return [
+                OrgMember(
+                    member_did=m["member_did"],
+                    role=m["role"],
+                    capabilities=m["capabilities"],
+                    issuer_did=m["issuer_did"],
+                    attestation_rid=m["attestation_rid"],
+                    revoked=m["revoked"],
+                    expires_at=m.get("expires_at"),
+                )
+                for m in raw
+            ]
+        except (ValueError, RuntimeError) as exc:
+            raise _map_error(exc, default_cls=OrgError) from exc
+
+    def get_member(
+        self,
+        org_did: str,
+        member_did: str,
+        repo_path: str | None = None,
+    ) -> OrgMember | None:
+        """Look up a specific member.
+
+        Args:
+            org_did: The organization's DID.
+            member_did: The member's DID to look up.
+
+        Returns:
+            OrgMember if found, or None.
+
+        Examples:
+            ```python
+            member = client.orgs.get_member(org.did, dev.did)
+            ```
+        """
+        members = self.list_members(org_did, include_revoked=False, repo_path=repo_path)
+        return next((m for m in members if m.member_did == member_did), None)