agent-protocols 0.7.0__tar.gz → 0.9.0__tar.gz

agent_protocols-0.9.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: agent-protocols
+Version: 0.9.0
+Summary: Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols
+Author: LDCLabs
+License: MIT
+Keywords: agent,protocol,ed25519,sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Requires-Dist: jsonschema<5,>=4.17
+Requires-Dist: rfc8785<0.2,>=0.1.4
+Provides-Extra: http
+Requires-Dist: requests<3,>=2.31; extra == "http"
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+
+# agent-protocols Python SDK
+
+Python SDK for the draft Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols.
+
+## Modules
+
+- `agent_protocols.identity`: `did:agent:` encoding, strict JSON parsing (`parse_strict_json`, `parse_envelope_json`), JCS canonicalization, event hashes, Ed25519 signing and strict verification (`verify_ed25519_strict`), closed event objects (`validate_event_fields`), clock-derived nonces with bounded `Max-Seen-Nonce` resynchronization, live-write and exact-resubmission checks (`verify_submission`), request JWT helpers.
+- `agent_protocols.profile`: `profile.update` payload helpers, delegation discovery hints, validation, succession checks, materialization.
+- `agent_protocols.delegation`: principal documents and resolution, Controller records with `supersedes` lineage, grant/revoke payloads, credentials, authority, acceptance, historical, and use checks, `verify_delegation_credential` over the latest grant record, and `audit_delegation_history` for auditors.
+- `agent_protocols.discourse`: the ADP kernel — twelve built-in event types, freshness classes, room policy (`invites`, `open_roles`), signed join requests and reviews, the type system with the portable type schema profile, redacted records, server records, and archive verification.
+- `agent_protocols.http_client`: optional requests-based Profile, Delegation, and Discourse clients. Install with `agent-protocols[http]`. Lists use `{"result", "next_cursor"}`; non-2xx responses raise `HttpResponseError` with the protocol `code`, `data`, and `max_seen_nonce`.
+
+## Example
+
+```python
+from agent_protocols import AgentSigner, ClientNonceManager, materialize_profile, profile_update_event, unix_ms
+
+signer = AgentSigner.generate()
+nonces = ClientNonceManager()
+created_at = unix_ms()
+event = profile_update_event(
+    signer.agent_id(),
+    created_at,
+    nonces.next_nonce(created_at),
+    {"id": signer.agent_id(), "name": "ResearchAgent-v3"},
+)
+envelope = signer.sign_event(event)
+profile = materialize_profile(envelope)
+```
+
+`next_nonce(created_at)` derives `max(last + 1, created_at)`, so nonces stay monotonic across restarts and devices. Agent Profile has no `username` field: the Agent ID is the identity key, and the latest profile is the accepted `profile.update` with the greatest `nonce`.
+
+ADP room writes carry a signed `base_seq` / `base_hash`. Message and control writes — `message.create` and custom `message` or `control` kinds — must be based at or after the room head, the latest `genesis`, `contract`, or `control` record, so messages never conflict with each other; contract writes (`room.update`, `room.close`, `room.cancel`, `type.define`) and signal writes, including the membership events, only anchor to an accepted record. Use `event_requires_room_head` and `event_advances_room_head` to tell them apart, `validate_room_base` for the host-side base check, `discourse_event` to build them, and `room_join_request_event` for a join request, which carries `room_id` but no base. Mentions are represented by the event-level `mentions` field, not by `payload.extra`.
+
+## Delegation
+
+Controllers are records shared by `controllers` and `retired_controllers`: `id` is the Agent ID, `source` is an HTTPS origin or `local`, and `valid_from` starts the binding. Omit `delegation` for a signing-only key, use `"*"` for full authority, or supply `{ "scopes": [...], "audiences": [...] }` for restricted authority. `supersedes` lets a successor key manage its predecessors' credentials. Retirement adds `retired_at`; compromise additionally sets `invalid_from`. A principal that grants delegations publishes `delegation_query_url`.
+
+Grants name the canonical `principal_id`. Credentials carry `principal_id`, an immutable `subject` and `owner_controller`, the latest `grant_event_id`, the service `accepted_at`, and `checked_at`. Materialization requires an explicit acceptance time and trusted previous state; it never derives acceptance time from `created_at`.
+
+The validation layers have different responsibilities:
+
+- Envelope validation checks cryptography, the closed event object, and payload shape, not principal authority.
+- Event-authority validation checks the controller policy before signing. Acceptance validation also checks the envelope and the authoritative-resolution URL.
+- Historical validation checks an accepted record `{"envelope", "accepted_at"}` against the original controller interval and ceiling. It does not authenticate a service receipt or prove offline revocation status.
+- Use validation checks audience, status, and validity. Applications still authenticate the subject and enforce the requested scopes and every constraint.
+
+```python
+# principal was freshly resolved over HTTPS; previous is trusted service state.
+validate_delegation_acceptance(envelope, principal, resolved_url, accepted_at, previous)
+credential = materialize_delegation_credential(
+    envelope, accepted_at=accepted_at, previous=previous,
+)
+
+# A relying party checks the credential's latest grant record.
+verdict = verify_delegation_credential(credential, records, principal, principal["id"], "https://dmsg.net", now)
+```
+
+Services remain responsible for fresh HTTPS resolution, live Identity timestamp and nonce checks, exact-resubmission lookups, atomic state and history storage, and current revocation or compromise reevaluation. These are SDK building blocks, not a hosted delegation service.
+
+`DelegationClient.discover(origin)` reads a delegation service's discovery document and prefers its endpoints. Transport implementations injected into the HTTP client must honor `allow_redirects=False`.
+
+## Running tests
+
+From the repository root, use the same dependency extra and runner as CI:
+
+```sh
+python3 -m pip install -e './python/agent-protocols[test]'
+python3 -m pytest python/agent-protocols/tests
+```
+
+The suite includes both `unittest.TestCase` classes and pytest functions. Running only `unittest discover` would omit the function-based conformance tests.

agent_protocols-0.9.0/README.md

@@ -0,0 +1,72 @@
+# agent-protocols Python SDK
+
+Python SDK for the draft Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols.
+
+## Modules
+
+- `agent_protocols.identity`: `did:agent:` encoding, strict JSON parsing (`parse_strict_json`, `parse_envelope_json`), JCS canonicalization, event hashes, Ed25519 signing and strict verification (`verify_ed25519_strict`), closed event objects (`validate_event_fields`), clock-derived nonces with bounded `Max-Seen-Nonce` resynchronization, live-write and exact-resubmission checks (`verify_submission`), request JWT helpers.
+- `agent_protocols.profile`: `profile.update` payload helpers, delegation discovery hints, validation, succession checks, materialization.
+- `agent_protocols.delegation`: principal documents and resolution, Controller records with `supersedes` lineage, grant/revoke payloads, credentials, authority, acceptance, historical, and use checks, `verify_delegation_credential` over the latest grant record, and `audit_delegation_history` for auditors.
+- `agent_protocols.discourse`: the ADP kernel — twelve built-in event types, freshness classes, room policy (`invites`, `open_roles`), signed join requests and reviews, the type system with the portable type schema profile, redacted records, server records, and archive verification.
+- `agent_protocols.http_client`: optional requests-based Profile, Delegation, and Discourse clients. Install with `agent-protocols[http]`. Lists use `{"result", "next_cursor"}`; non-2xx responses raise `HttpResponseError` with the protocol `code`, `data`, and `max_seen_nonce`.
+
+## Example
+
+```python
+from agent_protocols import AgentSigner, ClientNonceManager, materialize_profile, profile_update_event, unix_ms
+
+signer = AgentSigner.generate()
+nonces = ClientNonceManager()
+created_at = unix_ms()
+event = profile_update_event(
+    signer.agent_id(),
+    created_at,
+    nonces.next_nonce(created_at),
+    {"id": signer.agent_id(), "name": "ResearchAgent-v3"},
+)
+envelope = signer.sign_event(event)
+profile = materialize_profile(envelope)
+```
+
+`next_nonce(created_at)` derives `max(last + 1, created_at)`, so nonces stay monotonic across restarts and devices. Agent Profile has no `username` field: the Agent ID is the identity key, and the latest profile is the accepted `profile.update` with the greatest `nonce`.
+
+ADP room writes carry a signed `base_seq` / `base_hash`. Message and control writes — `message.create` and custom `message` or `control` kinds — must be based at or after the room head, the latest `genesis`, `contract`, or `control` record, so messages never conflict with each other; contract writes (`room.update`, `room.close`, `room.cancel`, `type.define`) and signal writes, including the membership events, only anchor to an accepted record. Use `event_requires_room_head` and `event_advances_room_head` to tell them apart, `validate_room_base` for the host-side base check, `discourse_event` to build them, and `room_join_request_event` for a join request, which carries `room_id` but no base. Mentions are represented by the event-level `mentions` field, not by `payload.extra`.
+
+## Delegation
+
+Controllers are records shared by `controllers` and `retired_controllers`: `id` is the Agent ID, `source` is an HTTPS origin or `local`, and `valid_from` starts the binding. Omit `delegation` for a signing-only key, use `"*"` for full authority, or supply `{ "scopes": [...], "audiences": [...] }` for restricted authority. `supersedes` lets a successor key manage its predecessors' credentials. Retirement adds `retired_at`; compromise additionally sets `invalid_from`. A principal that grants delegations publishes `delegation_query_url`.
+
+Grants name the canonical `principal_id`. Credentials carry `principal_id`, an immutable `subject` and `owner_controller`, the latest `grant_event_id`, the service `accepted_at`, and `checked_at`. Materialization requires an explicit acceptance time and trusted previous state; it never derives acceptance time from `created_at`.
+
+The validation layers have different responsibilities:
+
+- Envelope validation checks cryptography, the closed event object, and payload shape, not principal authority.
+- Event-authority validation checks the controller policy before signing. Acceptance validation also checks the envelope and the authoritative-resolution URL.
+- Historical validation checks an accepted record `{"envelope", "accepted_at"}` against the original controller interval and ceiling. It does not authenticate a service receipt or prove offline revocation status.
+- Use validation checks audience, status, and validity. Applications still authenticate the subject and enforce the requested scopes and every constraint.
+
+```python
+# principal was freshly resolved over HTTPS; previous is trusted service state.
+validate_delegation_acceptance(envelope, principal, resolved_url, accepted_at, previous)
+credential = materialize_delegation_credential(
+    envelope, accepted_at=accepted_at, previous=previous,
+)
+
+# A relying party checks the credential's latest grant record.
+verdict = verify_delegation_credential(credential, records, principal, principal["id"], "https://dmsg.net", now)
+```
+
+Services remain responsible for fresh HTTPS resolution, live Identity timestamp and nonce checks, exact-resubmission lookups, atomic state and history storage, and current revocation or compromise reevaluation. These are SDK building blocks, not a hosted delegation service.
+
+`DelegationClient.discover(origin)` reads a delegation service's discovery document and prefers its endpoints. Transport implementations injected into the HTTP client must honor `allow_redirects=False`.
+
+## Running tests
+
+From the repository root, use the same dependency extra and runner as CI:
+
+```sh
+python3 -m pip install -e './python/agent-protocols[test]'
+python3 -m pytest python/agent-protocols/tests
+```
+
+The suite includes both `unittest.TestCase` classes and pytest functions. Running only `unittest discover` would omit the function-based conformance tests.

{agent_protocols-0.7.0 → agent_protocols-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-protocols"
-version = "0.7.0"
+version = "0.9.0"
 description = "Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -15,6 +15,7 @@ dependencies = [
 
 [project.optional-dependencies]
 http = ["requests>=2.31,<3"]
+test = ["pytest>=8,<10"]
 
 [build-system]
 requires = ["setuptools>=68"]

{agent_protocols-0.7.0 → agent_protocols-0.9.0}/src/agent_protocols/__init__.py

@@ -1,17 +1,23 @@
 from .errors import AgentProtocolError
 from .identity import (
     AGENT_ID_PREFIX,
+    IDENTITY_EVENT_FIELDS,
+    MAX_NONCE_JUMP,
+    SHARED_ERROR_CODES,
     AgentSigner,
     ClientNonceManager,
     MAX_NONCE_HEADER,
     MemoryNonceStore,
     RequestBinding,
+    SubmissionResult,
     agent_id_from_public_key,
     canonical_event_bytes,
     create_event,
     create_request_jwt_claims,
     event_hash,
     event_hash_bytes,
+    parse_envelope_json,
+    parse_strict_json,
     public_key_bytes,
     service_origin,
     sign_event,
@@ -19,13 +25,17 @@ from .identity import (
     unix_ms,
     unix_secs,
     validate_agent_id,
+    validate_event_fields,
     validate_nonce,
+    validate_origin,
+    verify_ed25519_strict,
     verify_envelope,
     verify_event_hash,
     verify_event_hash_signature,
     verify_live_envelope,
     verify_request_jwt,
     verify_signature,
+    verify_submission,
     verify_timestamp,
     with_mention,
     with_mentions,
@@ -38,49 +48,80 @@ from .profile import (
     latest_profile_update,
     materialize_profile,
     profile_update_event,
+    validate_profile_payload,
+    validate_profile_succession,
     validate_profile_update,
 )
 from .delegation import (
+    DELEGATION_ERROR_CODES,
     DELEGATION_GRANT,
     DELEGATION_PROTOCOL,
     DELEGATION_REVOKE,
+    Controller,
+    DelegationPolicy,
+    DelegationRecord,
+    DelegationVerdict,
+    audit_delegation_history,
+    controller_lineage,
     delegation_grant_event,
     delegation_revoke_event,
     is_principal_alias,
     materialize_delegation_credential,
+    validate_audience,
+    validate_controller,
+    validate_controller_enumeration,
+    validate_delegation_acceptance,
     validate_delegation_envelope,
+    validate_delegation_event_authority,
     validate_delegation_grant_payload,
+    validate_delegation_id,
     validate_delegation_query_request,
     validate_delegation_revoke_payload,
+    validate_delegation_use,
+    validate_historical_delegation,
     validate_principal_document,
     validate_principal_resolution,
+    verify_delegation_credential,
 )
 
 __all__ = [
     "AGENT_ID_PREFIX",
+    "DELEGATION_ERROR_CODES",
     "DELEGATION_GRANT",
     "DELEGATION_PROTOCOL",
     "DELEGATION_REVOKE",
+    "IDENTITY_EVENT_FIELDS",
     "MAX_NONCE_HEADER",
+    "MAX_NONCE_JUMP",
     "PROFILE_PROTOCOL",
     "PROFILE_UPDATE",
+    "SHARED_ERROR_CODES",
     "AgentProtocolError",
     "AgentSigner",
     "ClientNonceManager",
+    "Controller",
+    "DelegationPolicy",
+    "DelegationRecord",
+    "DelegationVerdict",
     "MemoryNonceStore",
     "RequestBinding",
+    "SubmissionResult",
     "agent_id_from_public_key",
+    "audit_delegation_history",
     "canonical_event_bytes",
+    "controller_lineage",
     "create_event",
+    "create_request_jwt_claims",
     "delegation_grant_event",
     "delegation_revoke_event",
-    "create_request_jwt_claims",
     "event_hash",
     "event_hash_bytes",
-    "latest_profile_update",
-    "materialize_profile",
     "is_principal_alias",
+    "latest_profile_update",
     "materialize_delegation_credential",
+    "materialize_profile",
+    "parse_envelope_json",
+    "parse_strict_json",
     "profile_update_event",
     "public_key_bytes",
     "service_origin",
@@ -89,20 +130,35 @@ __all__ = [
     "unix_ms",
     "unix_secs",
     "validate_agent_id",
+    "validate_audience",
+    "validate_controller",
+    "validate_controller_enumeration",
+    "validate_delegation_acceptance",
     "validate_delegation_envelope",
+    "validate_delegation_event_authority",
     "validate_delegation_grant_payload",
+    "validate_delegation_id",
     "validate_delegation_query_request",
     "validate_delegation_revoke_payload",
+    "validate_delegation_use",
+    "validate_event_fields",
+    "validate_historical_delegation",
     "validate_nonce",
+    "validate_origin",
     "validate_principal_document",
     "validate_principal_resolution",
+    "validate_profile_payload",
+    "validate_profile_succession",
     "validate_profile_update",
+    "verify_delegation_credential",
+    "verify_ed25519_strict",
     "verify_envelope",
     "verify_event_hash",
     "verify_event_hash_signature",
     "verify_live_envelope",
     "verify_request_jwt",
     "verify_signature",
+    "verify_submission",
     "verify_timestamp",
     "with_mention",
     "with_mentions",