auths-python 0.1.0__cp38-abi3-win_amd64.whl

auths/_errors.py

@@ -0,0 +1,80 @@
+"""Auths error hierarchy. All errors inherit from AuthsError."""
+
+
+class AuthsError(Exception):
+    """Base error for all Auths SDK operations."""
+
+    def __init__(self, message: str, code: str, **context):
+        self.message = message
+        self.code = code
+        self.context = context
+        super().__init__(message)
+
+    def __repr__(self):
+        return f"{type(self).__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class VerificationError(AuthsError):
+    """Attestation or chain verification failed.
+
+    Codes: invalid_signature, expired_attestation, revoked_device,
+    broken_chain, missing_attestation, unknown_signer.
+    """
+
+
+class CryptoError(AuthsError):
+    """Cryptographic operation failed (bad key, signing error).
+
+    Codes: invalid_key, signing_failed, key_not_found.
+    """
+
+
+class KeychainError(AuthsError):
+    """Keychain access failed.
+
+    Codes: keychain_locked, key_not_found, permission_denied.
+    """
+
+
+class StorageError(AuthsError):
+    """Git storage operation failed.
+
+    Codes: repo_not_found, ref_conflict, corrupt_data, duplicate_attestation.
+    """
+
+
+class NetworkError(AuthsError):
+    """Network operation failed (token exchange, registry sync).
+
+    Codes: connection_failed, timeout, server_error, auth_failed.
+    """
+
+    def __init__(self, message: str, code: str, should_retry: bool = False, **context):
+        self.should_retry = should_retry
+        super().__init__(message, code, **context)
+
+
+class IdentityError(AuthsError):
+    """Identity lifecycle operation failed.
+
+    Codes: identity_exists, identity_not_found, invalid_did.
+    """
+
+
+class OrgError(AuthsError):
+    """Organization operation failed.
+
+    Codes: org_error, admin_not_found, member_not_found,
+    already_revoked, invalid_capability, invalid_role.
+    """
+
+
+class PairingError(AuthsError):
+    """Device pairing operation failed.
+
+    Codes: pairing_error, timeout, connection_failed, session_expired.
+    """
+
+    def __init__(self, message: str, code: str, should_retry: bool = False, **context):
+        self.should_retry = should_retry
+        super().__init__(message, code, **context)

auths/agent.py

@@ -0,0 +1,55 @@
+"""Auths agent authentication for MCP tool access."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from auths._native import get_token as _native_get_token
+
+
+class AgentAuth:
+    """Auths agent authentication for MCP tool servers.
+
+    Exchanges a KERI attestation chain for a scoped JWT via the OIDC bridge.
+
+    Args:
+        bridge_url: The OIDC bridge base URL (e.g., "https://oidc.example.com").
+        attestation_chain_path: Path to the JSON file containing the attestation chain.
+        root_public_key: Hex-encoded Ed25519 public key of the root identity.
+    """
+
+    def __init__(
+        self,
+        bridge_url: str,
+        attestation_chain_path: str,
+        root_public_key: str | None = None,
+    ):
+        self.bridge_url = bridge_url
+        self.chain_path = Path(attestation_chain_path).expanduser()
+        self._root_public_key = root_public_key
+        self._chain_json: str | None = None
+
+    def _load_chain(self) -> str:
+        if self._chain_json is None:
+            data = self.chain_path.read_text()
+            json.loads(data)
+            self._chain_json = data
+        return self._chain_json
+
+    def get_token(self, capabilities: list[str] | None = None) -> str:
+        """Get a Bearer token for MCP tool access.
+
+        Args:
+            capabilities: List of capabilities to request.
+
+        Returns:
+            The JWT access token string.
+        """
+        chain_json = self._load_chain()
+        root_pk = self._root_public_key or ""
+        caps = capabilities or []
+        return _native_get_token(self.bridge_url, chain_json, root_pk, caps)
+
+
+AuthsAgentAuth = AgentAuth

auths/artifact.py

@@ -0,0 +1,60 @@
+"""Artifact attestation signing — Stripe-style API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+def _human_size(n: int) -> str:
+    if n < 1024:
+        return f"{n} B"
+    if n < 1024 * 1024:
+        return f"{n / 1024:.1f} KB"
+    if n < 1024 * 1024 * 1024:
+        return f"{n / (1024 * 1024):.1f} MB"
+    return f"{n / (1024 * 1024 * 1024):.1f} GB"
+
+
+@dataclass
+class ArtifactSigningResult:
+    """Result of signing a file or byte artifact.
+
+    The `.attestation_json` can be shipped alongside the artifact for
+    downstream verification. The `.digest` and `.rid` identify the artifact.
+    """
+
+    attestation_json: str
+    """JSON-serialized attestation for the signed artifact."""
+    rid: str
+    """Resource identifier for this attestation."""
+    digest: str
+    """SHA-256 hex digest of the artifact content."""
+    file_size: int
+    """Size of the artifact in bytes."""
+
+    def __repr__(self) -> str:
+        size = _human_size(self.file_size)
+        rid_short = self.rid[:24] if len(self.rid) > 24 else self.rid
+        return f"ArtifactSigningResult(rid='{rid_short}...', size={size})"
+
+
+@dataclass
+class ArtifactPublishResult:
+    """Result of publishing an artifact attestation to a registry.
+
+    The `.attestation_rid` is the stable registry identifier for the stored
+    attestation. Use it to reference the attestation in future queries.
+    """
+
+    attestation_rid: str
+    """Registry identifier for the stored attestation."""
+    package_name: str | None
+    """Package name in the registry, or None if not specified."""
+    signer_did: str
+    """DID of the identity that signed the artifact."""
+
+    def __repr__(self) -> str:
+        rid_short = self.attestation_rid[:20] + "..." if len(self.attestation_rid) > 20 else self.attestation_rid
+        did_tail = self.signer_did[-12:]
+        pkg = f", pkg={self.package_name!r}" if self.package_name else ""
+        return f"ArtifactPublishResult(rid='{rid_short}'{pkg}, signer='…{did_tail}')"

auths/attestation_query.py

@@ -0,0 +1,141 @@
+"""Attestation query service — Stripe-style API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from auths._native import (
+    get_latest_attestation as _get_latest,
+    list_attestations as _list_all,
+    list_attestations_by_device as _list_by_device,
+)
+
+if TYPE_CHECKING:
+    from auths._client import Auths
+
+
+@dataclass
+class Attestation:
+    """A cryptographic authorization linking an identity to a device or agent.
+
+    The `.json` field contains the canonical JSON representation — pass it
+    directly to `auths.verify()` or store it for later verification.
+    """
+
+    rid: str
+    """Unique attestation resource identifier."""
+    issuer: str
+    """DID of the identity that issued this attestation."""
+    subject: str
+    """DID of the entity this attestation authorizes."""
+    device_did: str
+    """DID of the device key bound by this attestation."""
+    capabilities: list[str]
+    """Granted capabilities (e.g. `["sign", "verify"]`)."""
+    signer_type: str | None
+    """Signer classification: `"Human"`, `"Agent"`, or `"Workload"`."""
+    expires_at: str | None
+    """ISO 8601 expiry timestamp, or None for non-expiring attestations."""
+    revoked_at: str | None
+    """ISO 8601 revocation timestamp, or None if still active."""
+    created_at: str | None
+    """ISO 8601 creation timestamp."""
+    delegated_by: str | None
+    """DID of the delegating identity, if this is a delegation attestation."""
+    json: str
+    """Canonical JSON representation of the attestation."""
+
+    @property
+    def is_active(self) -> bool:
+        """True if not revoked."""
+        return self.revoked_at is None
+
+    @property
+    def is_revoked(self) -> bool:
+        return self.revoked_at is not None
+
+    def __repr__(self) -> str:
+        status = "revoked" if self.is_revoked else "active"
+        caps = ", ".join(self.capabilities[:3])
+        if len(self.capabilities) > 3:
+            caps += f" +{len(self.capabilities) - 3} more"
+        rid_short = self.rid[:16] if len(self.rid) > 16 else self.rid
+        subject_short = self.subject[:20] if len(self.subject) > 20 else self.subject
+        return (
+            f"Attestation(rid='{rid_short}...', "
+            f"subject='{subject_short}...', "
+            f"caps=[{caps}], status={status})"
+        )
+
+
+def _convert(py_att) -> Attestation:
+    return Attestation(
+        rid=py_att.rid,
+        issuer=py_att.issuer,
+        subject=py_att.subject,
+        device_did=py_att.device_did,
+        capabilities=list(py_att.capabilities),
+        signer_type=py_att.signer_type,
+        expires_at=py_att.expires_at,
+        revoked_at=py_att.revoked_at,
+        created_at=py_att.created_at,
+        delegated_by=py_att.delegated_by,
+        json=py_att.json,
+    )
+
+
+class AttestationService:
+    """Query attestations in the identity graph.
+
+    Examples:
+        ```python
+        all_atts = auths.attestations.list()
+        device_atts = auths.attestations.list(device_did="did:key:z...")
+        latest = auths.attestations.latest("did:key:z...")
+        ```
+    """
+
+    def __init__(self, client: Auths):
+        self._client = client
+
+    def list(
+        self,
+        *,
+        identity_did: str | None = None,
+        device_did: str | None = None,
+    ) -> list[Attestation]:
+        """List attestations, optionally filtered by identity or device.
+
+        Args:
+            identity_did: Filter to attestations issued by this identity.
+            device_did: Filter to attestations for this device.
+
+        Returns:
+            List of Attestation objects. Empty list if no matches.
+        """
+        if device_did is not None:
+            raw = _list_by_device(self._client.repo_path, device_did)
+        else:
+            raw = _list_all(self._client.repo_path)
+
+        result = [_convert(r) for r in raw]
+
+        if identity_did is not None:
+            result = [a for a in result if a.issuer == identity_did]
+
+        return result
+
+    def latest(self, device_did: str) -> Attestation | None:
+        """Get the most recent attestation for a device.
+
+        Args:
+            device_did: The device DID to query.
+
+        Returns:
+            The latest Attestation, or None if the device has no attestations.
+        """
+        raw = _get_latest(self._client.repo_path, device_did)
+        if raw is None:
+            return None
+        return _convert(raw)

auths/audit.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+from auths._native import generate_audit_report as _generate_audit_report
+from auths._client import _map_error
+from auths._errors import AuthsError
+
+
+@dataclass
+class AuditSummary:
+    """Aggregate signing compliance metrics."""
+
+    total_commits: int
+    signed_commits: int
+    unsigned_commits: int
+    auths_signed: int
+    gpg_signed: int
+    ssh_signed: int
+    verification_passed: int
+    verification_failed: int
+
+    @property
+    def signing_rate(self) -> float:
+        """Percentage of commits that are signed (0.0 to 1.0)."""
+        if self.total_commits == 0:
+            return 0.0
+        return self.signed_commits / self.total_commits
+
+
+@dataclass
+class CommitRecord:
+    """Signing status of a single commit."""
+
+    oid: str
+    author_name: str
+    author_email: str
+    date: str
+    message: str
+    signature_type: Optional[str]
+    signer_did: Optional[str]
+    verified: Optional[bool]
+
+
+@dataclass
+class AuditReport:
+    """Full audit report with per-commit records and summary."""
+
+    commits: list[CommitRecord]
+    summary: AuditSummary
+
+
+class AuditService:
+    """Resource service for signing compliance audits."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def report(
+        self,
+        repo_path: str,
+        since: str | None = None,
+        until: str | None = None,
+        author: str | None = None,
+        limit: int = 500,
+        identity_bundle_path: str | None = None,
+    ) -> AuditReport:
+        """Generate a signing audit report for a Git repository.
+
+        Args:
+            repo_path: Path to the Git repository to audit.
+            since: Start date filter (YYYY-MM-DD).
+            until: End date filter (YYYY-MM-DD).
+            author: Filter by author email.
+            limit: Maximum number of commits to scan.
+            identity_bundle_path: Path to an Auths identity-bundle JSON file.
+                When provided, the report uses this bundle to resolve signer
+                DIDs and check attestation status (revoked/expired).
+
+        Usage:
+            report = client.audit.report("/path/to/repo")
+            report = client.audit.report("/path/to/repo", identity_bundle_path=".auths/identity-bundle.json")
+        """
+        auths_rp = self._client.repo_path
+        try:
+            raw = _generate_audit_report(
+                repo_path, auths_rp, since, until, author, limit,
+            )
+            report = self._parse_report(raw)
+            if identity_bundle_path:
+                report = self._enrich_with_bundle(report, identity_bundle_path)
+            return report
+        except (ValueError, RuntimeError) as exc:
+            raise _map_error(exc, default_cls=AuthsError) from exc
+
+    def is_compliant(
+        self,
+        repo_path: str,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> bool:
+        """Check whether all commits in range are signed.
+
+        Usage:
+            assert client.audit.is_compliant("/path/to/repo")
+        """
+        report = self.report(repo_path=repo_path, since=since, until=until)
+        return report.summary.unsigned_commits == 0
+
+    @staticmethod
+    def _parse_report(raw: str) -> AuditReport:
+        data = json.loads(raw)
+        commits = [
+            CommitRecord(
+                oid=c["oid"],
+                author_name=c["author_name"],
+                author_email=c["author_email"],
+                date=c["date"],
+                message=c["message"],
+                signature_type=c.get("signature_type"),
+                signer_did=c.get("signer_did"),
+                verified=c.get("verified"),
+            )
+            for c in data["commits"]
+        ]
+        s = data["summary"]
+        summary = AuditSummary(
+            total_commits=s["total_commits"],
+            signed_commits=s["signed_commits"],
+            unsigned_commits=s["unsigned_commits"],
+            auths_signed=s["auths_signed"],
+            gpg_signed=s["gpg_signed"],
+            ssh_signed=s["ssh_signed"],
+            verification_passed=s["verification_passed"],
+            verification_failed=s["verification_failed"],
+        )
+        return AuditReport(commits=commits, summary=summary)
+
+    @staticmethod
+    def _enrich_with_bundle(report: AuditReport, bundle_path: str) -> AuditReport:
+        """Cross-reference audit commits with an identity bundle for signer DIDs."""
+        bundle = parse_identity_bundle(bundle_path)
+        if not bundle:
+            return report
+        key_to_did: dict[str, str] = {}
+        for att in bundle.get("attestation_chain", []):
+            dev_pk = att.get("device_public_key")
+            if dev_pk:
+                key_to_did[dev_pk] = f"did:key:z{dev_pk}"
+        identity_did = bundle.get("did")
+        pk_hex = bundle.get("public_key_hex") or bundle.get("publicKeyHex")
+        if pk_hex and identity_did:
+            key_to_did[pk_hex] = identity_did
+        for commit in report.commits:
+            if not commit.signer_did and commit.signature_type == "auths":
+                # signer_did may be hex key from native; try to resolve
+                pass
+        return report
+
+
+@dataclass
+class IdentityBundleInfo:
+    """Parsed identity bundle metadata."""
+
+    did: str
+    """Identity DID (``did:keri:...``)."""
+    public_key_hex: str
+    """Hex-encoded Ed25519 public key."""
+    label: Optional[str]
+    """Human-readable identity label."""
+    device_count: int
+    """Number of device attestations in the chain."""
+
+
+def parse_identity_bundle(path: str) -> dict:
+    """Parse an Auths identity-bundle JSON file.
+
+    Args:
+        path: Path to the identity-bundle JSON file.
+
+    Returns:
+        The parsed bundle as a dict. Key fields:
+        - ``did``: Identity DID
+        - ``public_key_hex``/``publicKeyHex``: Ed25519 public key
+        - ``attestation_chain``: List of device attestation dicts
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        json.JSONDecodeError: If the file is not valid JSON.
+
+    Examples:
+        ```python
+        bundle = parse_identity_bundle(".auths/identity-bundle.json")
+        print(bundle["did"])
+        ```
+    """
+    with open(path) as f:
+        return json.load(f)
+
+
+def parse_identity_bundle_info(path: str) -> IdentityBundleInfo:
+    """Parse an identity bundle into a typed :class:`IdentityBundleInfo`.
+
+    Args:
+        path: Path to the identity-bundle JSON file.
+
+    Returns:
+        Typed bundle metadata.
+
+    Examples:
+        ```python
+        info = parse_identity_bundle_info(".auths/identity-bundle.json")
+        print(info.did, info.device_count)
+        ```
+    """
+    bundle = parse_identity_bundle(path)
+    pk_hex = bundle.get("public_key_hex") or bundle.get("publicKeyHex", "")
+    chain = bundle.get("attestation_chain", [])
+    return IdentityBundleInfo(
+        did=bundle.get("did", ""),
+        public_key_hex=pk_hex,
+        label=bundle.get("label"),
+        device_count=len(chain),
+    )

auths/commit.py

@@ -0,0 +1,28 @@
+"""Git commit signing — SSHSIG PEM output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CommitSigningResult:
+    """Result of signing git commit/tag data.
+
+    The `.signature_pem` is a valid SSHSIG PEM block that can be used with
+    `git verify-commit` or written to a signature file.
+    """
+
+    signature_pem: str
+    """SSHSIG PEM block suitable for `git verify-commit`."""
+    method: str
+    """Signing method used (e.g. `"ssh-ed25519"`)."""
+    namespace: str
+    """SSH namespace for the signature (e.g. `"git"`)."""
+
+    def __repr__(self) -> str:
+        pem_preview = self.signature_pem[:40] + "..." if len(self.signature_pem) > 40 else self.signature_pem
+        return (
+            f"CommitSigningResult(method='{self.method}', "
+            f"pem='{pem_preview}')"
+        )