palonexus 0.2.2__tar.gz → 0.2.3__tar.gz

{palonexus-0.2.2 → palonexus-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: palonexus
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for the PaloNexus agent control plane
 Project-URL: Homepage, https://github.com/rogerchucker/palonexus-sdk
 Project-URL: Repository, https://github.com/rogerchucker/palonexus-sdk

palonexus-0.2.3/src/palonexus/_build.py

@@ -0,0 +1,2 @@
+# generated by the PaloNexus build hook
+SOURCE_REVISION = "39ef113f4586132b2f647567be91f2723cde3435"

{palonexus-0.2.2 → palonexus-0.2.3}/src/palonexus/_sdist_provenance.py

@@ -1,3 +1,3 @@
 # generated by the PaloNexus build hook
 SDIST_MARKER = "palonexus-sdk-sdist-v1"
-SOURCE_REVISION = "90b32d14d89ad419ce5ee7a4b3cee5ef3f6db5ce"
+SOURCE_REVISION = "39ef113f4586132b2f647567be91f2723cde3435"

{palonexus-0.2.2 → palonexus-0.2.3}/src/palonexus/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.3'
+__version_tuple__ = version_tuple = (0, 2, 3)
 
 __commit_id__ = commit_id = None

{palonexus-0.2.2 → palonexus-0.2.3}/src/palonexus/cli/commands.py

@@ -22,6 +22,7 @@ from packaging.version import InvalidVersion, Version
 from palonexus.developer.client import (
     DeveloperClient,
     DeveloperClientError,
+    RequestRejected,
     _origin,
     _registration_authority_profile,
     canonical_json,
@@ -379,6 +380,36 @@ def _project_client(
     return client, store, session, agent, descriptor, credential_name
 
 
+def _claim_project_client(
+    args: Namespace,
+) -> tuple[DeveloperClient, CredentialStore, dict[str, str], dict[str, Any]]:
+    try:
+        store = credential_store(
+            allow_file_fallback=getattr(args, "allow_file_credential_store", False)
+        )
+        session = store.load("session")
+        descriptor = _project_descriptor()
+        if session is None:
+            raise CommandError("pnxs login is required")
+        tenant_id = session.get("tenant_id")
+        owner = session.get("owner_subject")
+        if (
+            not isinstance(tenant_id, str)
+            or not tenant_id
+            or not isinstance(owner, str)
+            or not owner
+        ):
+            raise CommandError("stored developer session is invalid")
+        client = DeveloperClient(
+            os.environ.get("PNXS_API_URL", "https://api.palonexus.cloud")
+        )
+    except CredentialStoreUnavailable as error:
+        raise CommandError(f"credential access failed: {error}") from error
+    except DeveloperClientError as error:
+        raise CommandError(f"tenant API configuration failed: {error}") from error
+    return client, store, session, descriptor
+
+
 def _print_json(value: dict[str, Any]) -> None:
     print(json.dumps(value, sort_keys=True, separators=(",", ":")))
 
@@ -622,6 +653,14 @@ def agents_register(args: Namespace) -> int:
         agent["agent_generation"] = str(result["generation"])
         agent["registered_descriptor_digest"] = str(result["descriptor_digest"])
         store.save(credential_name, agent)
+    except RequestRejected as error:
+        if error.status_code == 409:
+            raise CommandError(
+                "agent registration failed: the agent already exists or conflicts. "
+                "For a web-created agent, use "
+                f"`pnxs agent attach {descriptor['name']}`."
+            ) from error
+        raise CommandError(f"agent registration failed: {error}") from error
     except (
         DeveloperClientError,
         CredentialStoreUnavailable,
@@ -638,6 +677,52 @@ def agents_register(args: Namespace) -> int:
     return 0
 
 
+def agent_attach(args: Namespace) -> int:
+    _require_standalone_registration_cli()
+    client, store, session, descriptor = _claim_project_client(args)
+    if args.name != descriptor["name"]:
+        raise CommandError(
+            f"agent name {args.name!r} does not match the local descriptor name "
+            f"{descriptor['name']!r}"
+        )
+    tenant_id = str(session["tenant_id"])
+    credential_name = f"agent:{tenant_id}:{args.name}"
+    try:
+        cli_version = installed_sdk_version()
+        client.require_cli_compatibility(session, cli_version)
+        store.create_if_absent(credential_name, generate_agent_credential())
+        agent = store.load(credential_name)
+        if agent is None:
+            raise CredentialStoreUnavailable("agent credential was not persisted")
+        result = client.attach_agent(
+            session, agent, descriptor, cli_version=cli_version
+        )
+        agent["agent_id"] = str(result["agent_id"])
+        agent["agent_generation"] = str(result["generation"])
+        agent["registered_descriptor_digest"] = str(result["descriptor_digest"])
+        agent["claim_id"] = str(result["claim_id"])
+        store.save(credential_name, agent)
+    except (
+        DeveloperClientError,
+        CredentialStoreUnavailable,
+        KeyError,
+        ScaffoldError,
+    ) as error:
+        raise CommandError(f"agent attach failed: {error}") from error
+    _print_json(result)
+    return 0
+
+
+def register_agent(args: Namespace) -> int:
+    descriptor = _project_descriptor()
+    if args.name != descriptor["name"]:
+        raise CommandError(
+            f"agent name {args.name!r} does not match the local descriptor name "
+            f"{descriptor['name']!r}"
+        )
+    return agents_register(args)
+
+
 def _new_ceiling_request(
     agent: dict[str, str], descriptor: dict[str, Any]
 ) -> tuple[str, dict[str, Any]]:

{palonexus-0.2.2 → palonexus-0.2.3}/src/palonexus/cli/main.py

@@ -49,6 +49,20 @@ def build_parser() -> argparse.ArgumentParser:
         command.add_argument("--allow-file-credential-store", action="store_true")
         command.set_defaults(handler=handler)
 
+    agent = subcommands.add_parser("agent", allow_abbrev=False)
+    singular_agent_commands = agent.add_subparsers(
+        dest="singular_agent_command", required=True
+    )
+    attach = singular_agent_commands.add_parser("attach", allow_abbrev=False)
+    attach.add_argument("name")
+    attach.add_argument("--allow-file-credential-store", action="store_true")
+    attach.set_defaults(handler=commands.agent_attach)
+
+    register = subcommands.add_parser("register", allow_abbrev=False)
+    register.add_argument("name")
+    register.add_argument("--allow-file-credential-store", action="store_true")
+    register.set_defaults(handler=commands.register_agent)
+
     run = subcommands.add_parser("run", allow_abbrev=False)
     run.add_argument("agent_file")
     run.add_argument("--input", required=True)

{palonexus-0.2.2 → palonexus-0.2.3}/src/palonexus/developer/client.py

@@ -381,6 +381,31 @@ _REGISTRATION_RESPONSE_FIELDS = {
     "not_before",
     "expires_at",
 }
+_CLAIM_CHALLENGE_FIELDS = {
+    "schema_version",
+    "challenge_id",
+    "agent_id",
+    "tenant_id",
+    "accountable_owner",
+    "generation",
+    "descriptor_digest",
+    "key_thumbprint",
+    "nonce",
+    "expires_at",
+    "status",
+}
+_CLAIM_RECEIPT_FIELDS = {
+    "schema_version",
+    "claim_id",
+    "agent_id",
+    "tenant_id",
+    "accountable_owner",
+    "descriptor_digest",
+    "key_thumbprint",
+    "generation",
+    "status",
+    "claimed_at",
+}
 _REVOCATION_RESPONSE_FIELDS = {
     "schema_version",
     "event_id",
@@ -602,6 +627,95 @@ def _registration_binding(
     return jwk, thumbprint, name, digest, authority_profile
 
 
+def _claim_binding(
+    agent: dict[str, str], descriptor: dict[str, Any]
+) -> tuple[dict[str, str], str, str, str]:
+    try:
+        jwk = json.loads(
+            _require_string(agent.get("public_key_jwk"), "agent public key")
+        )
+    except json.JSONDecodeError as error:
+        raise ProtocolError("invalid agent public key") from error
+    if (
+        not isinstance(jwk, dict)
+        or set(jwk) != {"kty", "crv", "x"}
+        or jwk.get("kty") != "OKP"
+        or jwk.get("crv") != "Ed25519"
+        or not all(isinstance(value, str) for value in jwk.values())
+    ):
+        raise ProtocolError("invalid agent public key")
+    thumbprint = hashlib.sha256(canonical_json(jwk)).hexdigest()
+    name = _require_string(descriptor.get("name"), "agent name")
+    digest = _require_string(descriptor.get("descriptor_digest"), "descriptor digest")
+    if re.fullmatch(r"[0-9a-f]{64}", digest) is None:
+        raise ProtocolError("invalid descriptor digest")
+    return jwk, thumbprint, name, digest
+
+
+def _validate_claim_challenge(
+    response: dict[str, Any],
+    *,
+    session: dict[str, str],
+    name: str,
+    descriptor_digest: str,
+    key_thumbprint: str,
+) -> dict[str, Any]:
+    if set(response) != _CLAIM_CHALLENGE_FIELDS:
+        raise ProtocolError("invalid agent claim challenge shape")
+    expected = {
+        "schema_version": "palonexus.developer-agent-claim-challenge/v1",
+        "agent_id": name,
+        "tenant_id": _require_string(session.get("tenant_id"), "tenant_id"),
+        "accountable_owner": _require_string(
+            session.get("owner_subject"), "owner_subject"
+        ),
+        "descriptor_digest": descriptor_digest,
+        "key_thumbprint": key_thumbprint,
+        "status": "pending",
+    }
+    if any(response.get(field) != value for field, value in expected.items()):
+        raise ProtocolError("agent claim challenge is not bound to the request")
+    challenge_id = _require_string(response.get("challenge_id"), "challenge ID")
+    if re.fullmatch(r"claim-[0-9a-f]{32}", challenge_id) is None:
+        raise ProtocolError("invalid agent claim challenge ID")
+    nonce = _require_string(response.get("nonce"), "claim nonce")
+    if re.fullmatch(r"[A-Za-z0-9_-]{43}", nonce) is None:
+        raise ProtocolError("invalid agent claim nonce")
+    _require_positive_int(response.get("generation"), "generation")
+    _require_timestamp(response.get("expires_at"), "claim expiry")
+    return response
+
+
+def _validate_claim_receipt(
+    response: dict[str, Any],
+    *,
+    session: dict[str, str],
+    name: str,
+    descriptor_digest: str,
+    key_thumbprint: str,
+    challenge_id: str,
+) -> dict[str, Any]:
+    if set(response) != _CLAIM_RECEIPT_FIELDS:
+        raise ProtocolError("invalid agent claim receipt shape")
+    expected = {
+        "schema_version": "palonexus.developer-agent-claim/v1",
+        "claim_id": challenge_id,
+        "agent_id": name,
+        "tenant_id": _require_string(session.get("tenant_id"), "tenant_id"),
+        "accountable_owner": _require_string(
+            session.get("owner_subject"), "owner_subject"
+        ),
+        "descriptor_digest": descriptor_digest,
+        "key_thumbprint": key_thumbprint,
+        "status": "attached",
+    }
+    if any(response.get(field) != value for field, value in expected.items()):
+        raise ProtocolError("agent claim receipt is not bound to the request")
+    _require_positive_int(response.get("generation"), "generation")
+    _require_timestamp(response.get("claimed_at"), "claimed_at")
+    return response
+
+
 def _validate_revocation_response(
     response: dict[str, Any],
     *,
@@ -1138,6 +1252,165 @@ class DeveloperClient:
             authority_profile=authority_profile,
         )
 
+    def attach_agent(
+        self,
+        session: dict[str, str],
+        agent: dict[str, str],
+        descriptor: dict[str, Any],
+        *,
+        cli_version: str | None = None,
+    ) -> dict[str, Any]:
+        """Bind a locally generated proof key to an owner-matched web registration."""
+        private = _decode_private_key(agent.get("private_key"))
+        jwk, thumbprint, name, digest = _claim_binding(agent, descriptor)
+        token = _require_string(session.get("session_token"), "session token")
+        metadata = (
+            {
+                "Palonexus-CLI-Contract": CLI_CONTRACT,
+                "Palonexus-CLI-Version": _require_string(
+                    cli_version, "installed CLI version"
+                ),
+            }
+            if cli_version is not None
+            else {}
+        )
+        request_value = {
+            "schema_version": "palonexus.developer-agent-claim-request/v1",
+            "descriptor_digest": digest,
+            "public_key_jwk": jwk,
+        }
+        request_body = canonical_json(request_value)
+        request_idempotency = hashlib.sha256(request_body).hexdigest()
+        request_digest = hashlib.sha256(
+            canonical_json(
+                {
+                    "body": request_value,
+                    "idempotency_key": request_idempotency,
+                }
+            )
+        ).hexdigest()
+        expected_challenge_id = (
+            "claim-"
+            + hashlib.sha256(
+                canonical_json(
+                    {
+                        "tenant_id": _require_string(
+                            session.get("tenant_id"), "tenant_id"
+                        ),
+                        "agent_id": name,
+                        "accountable_owner": _require_string(
+                            session.get("owner_subject"), "owner_subject"
+                        ),
+                        "request_digest": request_digest,
+                    }
+                )
+            ).hexdigest()[:32]
+        )
+        base_path = "/v1/developer/agents/" + quote(name, safe="") + "/claim-challenges"
+        status_path = base_path + "/" + quote(expected_challenge_id, safe="")
+        try:
+            challenge_response = self._request(
+                "POST",
+                base_path,
+                body=request_body,
+                headers={
+                    "Authorization": "Bearer " + token,
+                    "Idempotency-Key": request_idempotency,
+                    **metadata,
+                },
+                expected=201,
+                allowed_fields=_CLAIM_CHALLENGE_FIELDS,
+            )
+        except DeveloperClientError as original:
+            try:
+                recovered = self._request(
+                    "GET",
+                    status_path,
+                    headers={"Authorization": "Bearer " + token, **metadata},
+                    allowed_fields=_CLAIM_CHALLENGE_FIELDS | _CLAIM_RECEIPT_FIELDS,
+                )
+            except DeveloperClientError:
+                raise original from None
+            if set(recovered) == _CLAIM_RECEIPT_FIELDS:
+                return _validate_claim_receipt(
+                    recovered,
+                    session=session,
+                    name=name,
+                    descriptor_digest=digest,
+                    key_thumbprint=thumbprint,
+                    challenge_id=expected_challenge_id,
+                )
+            challenge_response = recovered
+        challenge = _validate_claim_challenge(
+            challenge_response,
+            session=session,
+            name=name,
+            descriptor_digest=digest,
+            key_thumbprint=thumbprint,
+        )
+        challenge_id = str(challenge["challenge_id"])
+        if challenge_id != expected_challenge_id:
+            raise ProtocolError("agent claim challenge has an unexpected ID")
+        message = canonical_json(
+            {
+                "accountable_owner": challenge["accountable_owner"],
+                "agent_id": challenge["agent_id"],
+                "challenge_id": challenge_id,
+                "descriptor_digest": challenge["descriptor_digest"],
+                "expires_at": challenge["expires_at"],
+                "generation": challenge["generation"],
+                "key_thumbprint": challenge["key_thumbprint"],
+                "nonce": challenge["nonce"],
+                "purpose": "palonexus.developer-agent-claim.v1",
+                "tenant_id": challenge["tenant_id"],
+            }
+        )
+        completion_body = canonical_json(
+            {
+                "schema_version": "palonexus.developer-agent-claim-completion/v1",
+                "challenge_id": challenge_id,
+                "nonce": challenge["nonce"],
+                "proof": {
+                    "alg": "EdDSA",
+                    "key_thumbprint": thumbprint,
+                    "signature": _b64url(private.sign(message)),
+                },
+            }
+        )
+        completion_path = base_path + "/" + quote(challenge_id, safe="") + "/complete"
+        try:
+            response = self._request(
+                "POST",
+                completion_path,
+                body=completion_body,
+                headers={
+                    "Authorization": "Bearer " + token,
+                    "Idempotency-Key": hashlib.sha256(completion_body).hexdigest(),
+                    **metadata,
+                },
+                allowed_fields=_CLAIM_RECEIPT_FIELDS,
+            )
+        except DeveloperClientError as original:
+            try:
+                response = self._request(
+                    "GET",
+                    status_path,
+                    headers={"Authorization": "Bearer " + token, **metadata},
+                    allowed_fields=_CLAIM_CHALLENGE_FIELDS | _CLAIM_RECEIPT_FIELDS,
+                )
+                if set(response) != _CLAIM_RECEIPT_FIELDS:
+                    raise original
+            except DeveloperClientError:
+                raise original from None
+        return _validate_claim_receipt(
+            response,
+            session=session,
+            name=name,
+            descriptor_digest=digest,
+            key_thumbprint=thumbprint,
+            challenge_id=challenge_id,
+        )
+
     def reconcile_agent_registration(
         self,
         session: dict[str, str],

palonexus-0.2.2/src/palonexus/_build.py

@@ -1,2 +0,0 @@
-# generated by the PaloNexus build hook
-SOURCE_REVISION = "90b32d14d89ad419ce5ee7a4b3cee5ef3f6db5ce"