agentaddress 0.9.1__py3-none-any.whl

aap/__init__.py

@@ -0,0 +1,327 @@
+"""aap — reference Python implementation of the Agent Address Protocol."""
+
+from aap.address import Address
+from aap.envelope import Envelope, EnvelopeError
+from aap.encryption import (
+    ENCRYPTED_ENVELOPE_TYPE,
+    HPKE_ALGORITHM,
+    EncryptedEnvelope,
+    EncryptionError,
+    decrypt_envelope,
+    derive_encryption_keypair,
+    encrypt_envelope,
+    encryption_key_id,
+    encryption_public_from_private,
+    generate_encryption_keypair,
+)
+from aap.envelope_policy import (
+    DEFAULT_ENVELOPE_MAX_AGE_SECONDS,
+    DEFAULT_FUTURE_SKEW_SECONDS,
+    EnvelopePolicyError,
+    EnvelopeReplayCache,
+    envelope_replay_key,
+    parse_rfc3339,
+    validate_envelope_iat,
+    verify_envelope,
+)
+from aap.keys import (
+    decode_b64url,
+    encode_b64url,
+    generate_keypair,
+    seed_to_keypair,
+    sign,
+    verify,
+)
+from aap.payloads import (
+    AgentCard,
+    DiscoveryIntroductionRequest,
+    DiscoveryIntroductionResponse,
+    DiscoveryQueryResponse,
+    GroupComplete,
+    GroupInvitation,
+    GroupLeave,
+    GroupMembershipUpdate,
+    RelationshipAccept,
+    RelationshipDecline,
+    RelationshipProposal,
+    RelationshipRevoke,
+    ServiceFollowup,
+    ServiceFollowupGrant,
+    ServiceRequest,
+    ServiceResponse,
+    ServiceResponseStatus,
+    VerificationAttestation,
+    VerifyConfirmResponse,
+    VerifyStartResponse,
+    VerifiedIdentity,
+)
+from aap.group_flow import (
+    build_group_complete_envelope,
+    build_group_invitation_envelope,
+    build_group_leave_envelope,
+    build_group_membership_update_envelope,
+)
+from aap.messages import (
+    CHAT_PAYLOAD_TYPE,
+    ROUTING_ENVELOPE_TYPE,
+    UnsupportedPayloadType,
+    build_chat_envelope,
+    unwrap_chat_envelope,
+    wrap_routing_envelope,
+)
+from aap.host_policy import (
+    DEFAULT_LIFETIME_DAYS,
+    HIGH_RISK_LIFETIME_DAYS,
+    WILDCARD,
+    is_high_risk_scope,
+    should_auto_renew,
+    token_lifetime_days,
+)
+from aap.inbound import (
+    InboundPolicyError,
+    ValidatedChat,
+    ValidatedEnvelope,
+    validate_inbound_chat,
+    validate_inbound_envelope,
+)
+from aap.trusted_verifiers import VerifierTrustListEntry, parse_trusted_verifiers
+from aap.transport import InsecureTransportError, require_secure_url
+from aap.client import AAPClient, AAPClientError, AgentCardKeyChanged, KeyChangeRejected
+from aap.did_web import (
+    DIDWebError,
+    KeyPinChanged,
+    KeyPins,
+    did_web_document_url,
+    did_web_domain,
+    resolve_did_web_key,
+)
+from aap.identity import IdentityFile, load_or_generate
+from aap.verifier_client import (
+    VerifierClientError,
+    VerifyStartResult,
+    confirm_email_verification,
+    confirm_sms_verification,
+    start_email_verification,
+    start_sms_verification,
+)
+from aap.verifiers import (
+    DEFAULT_TRUSTED_VERIFIERS_URL,
+    TRUSTED_VERIFIERS_ISSUER,
+    TRUSTED_VERIFIERS_PAYLOAD_TYPE,
+    TrustListCache,
+    VerifierPubkeyCache,
+    trusted_verifiers_supporting,
+    verifier_relay_address,
+)
+from aap.relationships import (
+    RelationshipRecord,
+    RelationshipRevocationRecord,
+    RelationshipStore,
+    VALID_RELATIONSHIP_TYPES,
+    build_relationship_accept_envelope,
+    build_relationship_decline_envelope,
+    build_relationship_proposal_envelope,
+    build_relationship_revoke_envelope,
+)
+from aap.services import (
+    SERVICE_CATALOG_PAYLOAD_TYPE,
+    ServiceCatalog,
+    ServiceCatalogCache,
+    ServiceCatalogPayload,
+    ServiceDefinition,
+    ValidationFailure,
+    build_service_catalog_envelope,
+    build_service_request_envelope,
+    build_service_response_envelope,
+    validate_service_payload,
+)
+from aap.service_followups import (
+    FollowupGrantStore,
+    StoredFollowupGrant,
+    build_followup_envelope,
+    build_followup_grant_envelope,
+    parse_iso_duration,
+)
+from aap.conversations import (
+    Conversation,
+    ConversationEventRecord,
+    ConversationPolicyError,
+    ConversationStore,
+    broadcast_to_conversation,
+)
+from aap.pending_responses import PendingResponses
+from aap.stores.attestations import AttestationStore, StoredAttestation
+from aap.stores.consent import PendingConsent
+from aap.stores.identity_bindings import IdentityBinding, IdentityBindingStore
+from aap.stores.outbound_contacts import DEFAULT_REPLY_WINDOW, OutboundContactStore
+from aap.discovery import (
+    build_introduction_response_envelope,
+    extract_searcher_identities,
+    query_discovery,
+)
+from aap.stores.pending_introductions import PendingIntroductionRow, PendingIntroductions
+from aap.stores.pending_proposals import (
+    PendingInbound,
+    PendingOutbound,
+    PendingProposalStore,
+)
+from aap.stores.verification_flow import PendingVerifications, PendingVerificationRow
+from aap.stores.service_request_groups import ServiceRequestGroupIndex
+from aap.stores.service_requests import (
+    ServiceRequestStore,
+    StoredServiceRequest,
+    StoredServiceResponse,
+)
+from aap.version import __version__
+
+__all__ = [
+    "__version__",
+    "AAPClient",
+    "AAPClientError",
+    "AgentCardKeyChanged",
+    "Address",
+    "AgentCard",
+    "AttestationStore",
+    "CHAT_PAYLOAD_TYPE",
+    "Conversation",
+    "ConversationEventRecord",
+    "ConversationPolicyError",
+    "ConversationStore",
+    "DEFAULT_LIFETIME_DAYS",
+    "DEFAULT_ENVELOPE_MAX_AGE_SECONDS",
+    "DEFAULT_FUTURE_SKEW_SECONDS",
+    "DEFAULT_REPLY_WINDOW",
+    "DEFAULT_TRUSTED_VERIFIERS_URL",
+    "TRUSTED_VERIFIERS_ISSUER",
+    "TRUSTED_VERIFIERS_PAYLOAD_TYPE",
+    "DIDWebError",
+    "KeyPinChanged",
+    "KeyPins",
+    "DiscoveryIntroductionRequest",
+    "DiscoveryIntroductionResponse",
+    "DiscoveryQueryResponse",
+    "Envelope",
+    "EnvelopeError",
+    "EnvelopePolicyError",
+    "EnvelopeReplayCache",
+    "ENCRYPTED_ENVELOPE_TYPE",
+    "EncryptedEnvelope",
+    "EncryptionError",
+    "FollowupGrantStore",
+    "GroupComplete",
+    "GroupInvitation",
+    "GroupLeave",
+    "GroupMembershipUpdate",
+    "HIGH_RISK_LIFETIME_DAYS",
+    "HPKE_ALGORITHM",
+    "IdentityBinding",
+    "IdentityBindingStore",
+    "IdentityFile",
+    "InsecureTransportError",
+    "InboundPolicyError",
+    "KeyChangeRejected",
+    "OutboundContactStore",
+    "PendingConsent",
+    "PendingIntroductionRow",
+    "PendingIntroductions",
+    "PendingInbound",
+    "PendingOutbound",
+    "PendingProposalStore",
+    "PendingResponses",
+    "PendingVerificationRow",
+    "PendingVerifications",
+    "ROUTING_ENVELOPE_TYPE",
+    "SERVICE_CATALOG_PAYLOAD_TYPE",
+    "RelationshipAccept",
+    "RelationshipDecline",
+    "RelationshipProposal",
+    "RelationshipRecord",
+    "RelationshipRevocationRecord",
+    "RelationshipRevoke",
+    "RelationshipStore",
+    "ServiceCatalog",
+    "ServiceCatalogCache",
+    "ServiceCatalogPayload",
+    "ServiceDefinition",
+    "ServiceFollowup",
+    "ServiceFollowupGrant",
+    "ServiceRequest",
+    "ServiceRequestGroupIndex",
+    "ServiceRequestStore",
+    "ServiceResponse",
+    "ServiceResponseStatus",
+    "StoredAttestation",
+    "StoredFollowupGrant",
+    "StoredServiceRequest",
+    "StoredServiceResponse",
+    "TrustListCache",
+    "UnsupportedPayloadType",
+    "VALID_RELATIONSHIP_TYPES",
+    "ValidationFailure",
+    "VerificationAttestation",
+    "VerifyConfirmResponse",
+    "VerifyStartResponse",
+    "VerifiedIdentity",
+    "VerifierClientError",
+    "VerifierPubkeyCache",
+    "VerifierTrustListEntry",
+    "VerifyStartResult",
+    "ValidatedChat",
+    "ValidatedEnvelope",
+    "WILDCARD",
+    "broadcast_to_conversation",
+    "build_chat_envelope",
+    "build_followup_envelope",
+    "build_followup_grant_envelope",
+    "build_group_complete_envelope",
+    "build_group_invitation_envelope",
+    "build_group_leave_envelope",
+    "build_group_membership_update_envelope",
+    "build_introduction_response_envelope",
+    "build_relationship_accept_envelope",
+    "build_relationship_decline_envelope",
+    "build_relationship_proposal_envelope",
+    "build_relationship_revoke_envelope",
+    "build_service_catalog_envelope",
+    "build_service_request_envelope",
+    "build_service_response_envelope",
+    "confirm_email_verification",
+    "confirm_sms_verification",
+    "decode_b64url",
+    "did_web_document_url",
+    "did_web_domain",
+    "decrypt_envelope",
+    "derive_encryption_keypair",
+    "encode_b64url",
+    "encrypt_envelope",
+    "encryption_key_id",
+    "encryption_public_from_private",
+    "envelope_replay_key",
+    "extract_searcher_identities",
+    "generate_keypair",
+    "generate_encryption_keypair",
+    "is_high_risk_scope",
+    "load_or_generate",
+    "parse_iso_duration",
+    "parse_rfc3339",
+    "parse_trusted_verifiers",
+    "query_discovery",
+    "require_secure_url",
+    "resolve_did_web_key",
+    "seed_to_keypair",
+    "should_auto_renew",
+    "sign",
+    "start_email_verification",
+    "start_sms_verification",
+    "token_lifetime_days",
+    "trusted_verifiers_supporting",
+    "unwrap_chat_envelope",
+    "validate_inbound_chat",
+    "validate_inbound_envelope",
+    "validate_service_payload",
+    "validate_envelope_iat",
+    "verifier_relay_address",
+    "verify",
+    "verify_envelope",
+    "wrap_routing_envelope",
+]

aap/address.py

@@ -0,0 +1,88 @@
+"""AAP address: <localpart>^<domain>.
+
+Localpart accepts ASCII alphanumerics, '.', '-', '_'. Case-insensitive
+— normalised to lowercase on parse so ``Chris-work`` and ``chris-work``
+route to the same agent. Max length 64.
+
+Domain accepts ASCII alphanumerics, '.', '-'. Normalised to lowercase
+on parse (DNS labels are case-insensitive). Max length 253.
+
+The ``^`` separator was chosen because it (a) is easy to type
+(shift+6 on the number row), (b) is shell- and URL-safe in practice,
+and (c) appears in neither the localpart nor the domain grammar, so
+the split is unambiguous. The format intentionally does not resemble
+an email address.
+
+DNS-level checks (label length, leading/trailing hyphen, IDN punycode)
+happen at resolution time, not parse time.
+"""
+
+from dataclasses import dataclass
+
+_LOCALPART_MAX = 64
+_DOMAIN_MAX = 253
+# `+` is allowed in the localpart so derivative addresses like
+# `chris+work^…` parse cleanly. The address-claim system uses the
+# part before the first `+` as the base; for parsing purposes here `+`
+# is just another permitted character.
+_ALLOWED_LOCALPART_EXTRA = frozenset(".-_+")
+_ALLOWED_DOMAIN_EXTRA = frozenset(".-")
+
+
+def _valid_localpart_char(c: str) -> bool:
+    return (c.isalnum() and c.isascii()) or (c in _ALLOWED_LOCALPART_EXTRA)
+
+
+def _valid_domain_char(c: str) -> bool:
+    return (c.isalnum() and c.isascii()) or (c in _ALLOWED_DOMAIN_EXTRA)
+
+
+@dataclass(frozen=True)
+class Address:
+    localpart: str
+    domain: str
+
+    @classmethod
+    def parse(cls, s: str) -> "Address":
+        if "^" not in s:
+            raise ValueError(f"AAP address must contain '^': {s!r}")
+        localpart, domain = s.rsplit("^", 1)
+        if not localpart:
+            raise ValueError("localpart cannot be empty")
+        if not domain:
+            raise ValueError("domain cannot be empty")
+        if len(localpart) > _LOCALPART_MAX:
+            raise ValueError(
+                f"localpart too long ({len(localpart)} > {_LOCALPART_MAX})"
+            )
+        if not all(_valid_localpart_char(c) for c in localpart):
+            raise ValueError(f"localpart contains invalid characters: {localpart!r}")
+        localpart = localpart.lower()
+        if len(domain) > _DOMAIN_MAX:
+            raise ValueError(f"domain too long ({len(domain)} > {_DOMAIN_MAX})")
+        domain = domain.lower()
+        if not all(_valid_domain_char(c) for c in domain):
+            raise ValueError(f"domain contains invalid characters: {domain!r}")
+        return cls(localpart=localpart, domain=domain)
+
+    @classmethod
+    def parse_user_input(
+        cls,
+        s: str,
+        *,
+        default_domain: str = "agentaddress.org",
+    ) -> "Address":
+        """Parse human/LLM-entered address text.
+
+        A trailing caret is shorthand for the hosted Agent Address namespace:
+        ``chris^`` expands to ``chris^agentaddress.org``. The expanded value is
+        then passed through strict parsing so protocol validation remains in one
+        place.
+        """
+        value = s.strip()
+        if value.endswith("^"):
+            value = f"{value}{default_domain}"
+        return cls.parse(value)
+
+    def __str__(self) -> str:
+        return f"{self.localpart}^{self.domain}"