palonexus 0.1.0__py3-none-any.whl

agentdid/__init__.py

@@ -0,0 +1,73 @@
+"""agentdid — AgentDID + Verifiable Credentials cryptographic foundation.
+
+CONTRACTS §12. Imported by the IDP, the agents, and runbooks-api.
+
+    from agentdid import (
+        generate_keypair, did_for, did_key_for, build_did_document, Resolver,
+        issue_vc, verify_vc, build_vp, verify_vp, verify_delegation_chain,
+        make_challenge, respond_challenge, verify_challenge, state_commitment,
+        enforce_capability, is_revoked,
+    )
+"""
+from __future__ import annotations
+
+from .capability import enforce_capability, resource_matches, state_commitment
+from .challenge import make_challenge, respond_challenge, verify_challenge
+from .delegation import verify_delegation_chain
+from .did import DEFAULT_HOST, ROOT_DID, build_did_document, did_for, did_key_for, kid_for
+from .keys import (
+    b58decode,
+    b58encode,
+    generate_keypair,
+    multibase_to_pub,
+    multibase_to_raw,
+    priv_from_b64,
+    pub_to_multibase,
+    raw_to_multibase,
+)
+from .resolver import Resolver, did_web_to_url
+from .revocation import is_revoked
+from .vc import issue_vc, verify_vc
+from .vp import build_vp, verify_vp
+
+__all__ = [
+    # keys
+    "generate_keypair",
+    "pub_to_multibase",
+    "multibase_to_pub",
+    "multibase_to_raw",
+    "raw_to_multibase",
+    "priv_from_b64",
+    "b58encode",
+    "b58decode",
+    # did
+    "did_for",
+    "did_key_for",
+    "kid_for",
+    "build_did_document",
+    "ROOT_DID",
+    "DEFAULT_HOST",
+    # resolver
+    "Resolver",
+    "did_web_to_url",
+    # vc
+    "issue_vc",
+    "verify_vc",
+    # vp
+    "build_vp",
+    "verify_vp",
+    # delegation
+    "verify_delegation_chain",
+    # challenge / state
+    "make_challenge",
+    "respond_challenge",
+    "verify_challenge",
+    "state_commitment",
+    # capability
+    "enforce_capability",
+    "resource_matches",
+    # revocation
+    "is_revoked",
+]
+
+__version__ = "0.1.0"

agentdid/capability.py

@@ -0,0 +1,95 @@
+"""Capability enforcement + state commitment (CONTRACTS §12.2, §12.3, §6 plan).
+
+Capability shape (§12.3)::
+
+    { "action": "runbook:read",
+      "resource": "runbooks-api:/runbooks/*",
+      "constraints": { "notBefore", "notAfter", "maxCalls": 5,
+                       "execContext": { "ticketSource": "incy" } } }
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from datetime import datetime, timezone
+
+
+def state_commitment(state: dict) -> str:
+    """SHA-256 hex over canonical JSON (sorted keys, no whitespace)."""
+    canonical = json.dumps(state, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+# --- time helpers ------------------------------------------------------------
+def _to_epoch(value) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    s = str(value)
+    # ISO 8601, accept trailing Z
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(s)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    except ValueError:
+        return None
+
+
+# --- glob resource match -----------------------------------------------------
+def resource_matches(pattern: str, resource: str) -> bool:
+    """Match ``resource`` against ``pattern``. Supports a trailing ``/*`` wildcard
+    meaning "this prefix and anything below it". Exact match otherwise.
+    """
+    if pattern == resource:
+        return True
+    if pattern.endswith("/*"):
+        prefix = pattern[:-2]  # drop '/*'
+        # match the prefix itself or prefix + '/...'
+        return resource == prefix or resource.startswith(prefix + "/")
+    if pattern.endswith("*"):  # generic trailing wildcard
+        return resource.startswith(pattern[:-1])
+    return False
+
+
+def _is_subset(sub: dict, sup: dict) -> bool:
+    """Every key/value in ``sub`` must be present and equal in ``sup``."""
+    for k, v in sub.items():
+        if k not in sup or sup[k] != v:
+            return False
+    return True
+
+
+def enforce_capability(capability: dict, *, action: str, resource: str, context: dict) -> bool:
+    """Enforce a capability against a concrete request.
+
+    Checks:
+      - action equals the capability action
+      - resource glob-matches the capability resource (trailing ``/*`` supported)
+      - current time within ``constraints.notBefore`` / ``notAfter`` (if set)
+      - ``constraints.execContext`` is a subset of ``context``
+
+    NOTE: ``maxCalls`` is a stateful rate cap and is NOT enforced here — the
+    caller (verifier) must track call counts and enforce it. This function is
+    pure and stateless.
+    """
+    if capability.get("action") != action:
+        return False
+    if not resource_matches(capability.get("resource", ""), resource):
+        return False
+    constraints = capability.get("constraints") or {}
+    now = time.time()
+    nb = _to_epoch(constraints.get("notBefore"))
+    na = _to_epoch(constraints.get("notAfter"))
+    if nb is not None and now < nb:
+        return False
+    if na is not None and now > na:
+        return False
+    exec_ctx = constraints.get("execContext") or {}
+    if exec_ctx and not _is_subset(exec_ctx, context or {}):
+        return False
+    return True

agentdid/challenge.py

@@ -0,0 +1,93 @@
+"""Challenge-response for live execution-state verification (CONTRACTS §12.2; plan §5).
+
+Flow:
+  verifier  ->  make_challenge(required_state)  -> { nonce, required_state }
+  holder    ->  respond_challenge(...)          -> { state, state_commitment, sig, kid }
+  verifier  ->  verify_challenge(...)           -> bool
+
+The signature is EdDSA over the ASCII string ``f"{nonce}.{state_commitment}"``.
+"""
+from __future__ import annotations
+
+import base64
+import os
+
+from cryptography.exceptions import InvalidSignature
+
+from .capability import _is_subset, state_commitment
+from .did import kid_for
+from .keys import priv_from_b64
+
+
+def make_challenge(required_state: list) -> dict:
+    """Create a challenge with a fresh nonce and the required state field names."""
+    nonce = os.urandom(16).hex()
+    return {"nonce": nonce, "required_state": list(required_state)}
+
+
+def _signing_input(nonce: str, commitment: str) -> bytes:
+    return f"{nonce}.{commitment}".encode("utf-8")
+
+
+def respond_challenge(holder_priv_b64: str, holder_did: str, nonce: str, state: dict) -> dict:
+    """Sign a challenge response proving the holder's current execution state."""
+    commitment = state_commitment(state)
+    priv = priv_from_b64(holder_priv_b64)
+    sig = priv.sign(_signing_input(nonce, commitment))
+    return {
+        "state": state,
+        "state_commitment": commitment,
+        "sig": base64.b64encode(sig).decode("ascii"),
+        "kid": kid_for(holder_did),
+    }
+
+
+def verify_challenge(resp: dict, holder_did: str, resolver, *, nonce: str, constraints: dict) -> bool:
+    """Verify a challenge response.
+
+    Checks:
+      - signature over ``nonce.state_commitment`` via the holder's DID key,
+      - the recomputed commitment of ``resp["state"]`` matches ``state_commitment``,
+      - the state satisfies ``constraints``:
+          * ``constraints["execContext"]`` is a subset of the state (if present),
+          * every name in ``constraints["required_state"]`` (or
+            ``constraints["required"]``) is present and non-empty in the state.
+    Returns True only if everything holds.
+    """
+    try:
+        state = resp["state"]
+        claimed_commitment = resp["state_commitment"]
+        sig = base64.b64decode(resp["sig"])
+        kid = resp.get("kid") or kid_for(holder_did)
+    except (KeyError, TypeError, ValueError):
+        return False
+
+    # kid must belong to the asserted holder.
+    if kid.split("#")[0] != holder_did:
+        return False
+
+    # Recompute and compare the commitment (defeats tampered state).
+    if state_commitment(state) != claimed_commitment:
+        return False
+
+    # Verify the signature against the holder's DID key.
+    try:
+        pub = resolver.public_key(kid)
+        pub.verify(sig, _signing_input(nonce, claimed_commitment))
+    except (InvalidSignature, Exception):
+        return False
+
+    # execContext subset check.
+    exec_ctx = (constraints or {}).get("execContext") or {}
+    if exec_ctx and not _is_subset(exec_ctx, state):
+        return False
+
+    # required fields present and non-empty.
+    required = (constraints or {}).get("required_state") or (constraints or {}).get("required") or []
+    for field in required:
+        if field not in state:
+            return False
+        v = state[field]
+        if v is None or v == "" or v == [] or v == {}:
+            return False
+    return True

agentdid/delegation.py

@@ -0,0 +1,123 @@
+"""Delegation-chain verification (CONTRACTS §12.2, §12.6; plan §6).
+
+A leaf delegation VC embeds its parent VC JWT under ``vc.parent``. We walk the
+chain leaf -> ... -> root, verifying:
+
+  - each link's signature via its issuer DID key (resolved from the registry),
+  - the chain terminates at a ``CapabilityCredential`` whose ``iss == root_did``,
+  - each child capability is a subset (⊆) of its parent capability:
+        * same action,
+        * child resource matches / is narrower than the parent resource,
+        * child time window within the parent window,
+        * child execContext ⊇ parent execContext (more constraints = narrower),
+  - the leaf capability authorizes the requested ``action`` / ``resource``.
+"""
+from __future__ import annotations
+
+from .capability import _to_epoch, resource_matches
+from .vc import verify_vc
+
+
+def _window(cap: dict) -> tuple[float | None, float | None]:
+    c = cap.get("constraints") or {}
+    return _to_epoch(c.get("notBefore")), _to_epoch(c.get("notAfter"))
+
+
+def _exec_ctx(cap: dict) -> dict:
+    return (cap.get("constraints") or {}).get("execContext") or {}
+
+
+def _capability_subset(child: dict, parent: dict) -> bool:
+    """True if ``child`` capability is ⊆ ``parent`` capability."""
+    if child.get("action") != parent.get("action"):
+        return False
+    # child resource must be matched/covered by the parent resource pattern.
+    if not resource_matches(parent.get("resource", ""), child.get("resource", "")):
+        return False
+    # time window: child must be within parent's window.
+    c_nb, c_na = _window(child)
+    p_nb, p_na = _window(parent)
+    if p_nb is not None:
+        if c_nb is None or c_nb < p_nb:
+            return False
+    if p_na is not None:
+        if c_na is None or c_na > p_na:
+            return False
+    # execContext: child must carry at least every constraint the parent has
+    # (child execContext ⊇ parent execContext), with matching values.
+    p_ctx = _exec_ctx(parent)
+    c_ctx = _exec_ctx(child)
+    for k, v in p_ctx.items():
+        if k not in c_ctx or c_ctx[k] != v:
+            return False
+    return True
+
+
+def _cap_of(claims: dict) -> dict | None:
+    return (claims.get("vc", {}).get("credentialSubject", {}) or {}).get("capability")
+
+
+def _types_of(claims: dict) -> list:
+    return claims.get("vc", {}).get("type", []) or []
+
+
+def verify_delegation_chain(
+    leaf_vc_jwt: str,
+    resolver,
+    *,
+    root_did: str,
+    action: str,
+    resource: str,
+    status_url: str | None = None,
+    max_depth: int = 16,
+) -> bool:
+    """Return True iff the delegation chain is fully valid (see module docstring)."""
+    try:
+        leaf_claims = verify_vc(leaf_vc_jwt, resolver, status_url=status_url)
+    except Exception:
+        return False
+
+    leaf_cap = _cap_of(leaf_claims)
+    if not leaf_cap:
+        return False
+    # The leaf must actually authorize the requested action/resource.
+    if leaf_cap.get("action") != action:
+        return False
+    if not resource_matches(leaf_cap.get("resource", ""), resource):
+        return False
+
+    current_jwt = leaf_vc_jwt
+    current_claims = leaf_claims
+    depth = 0
+    while True:
+        depth += 1
+        if depth > max_depth:
+            return False
+        parent_jwt = current_claims.get("vc", {}).get("parent")
+        if parent_jwt is None:
+            # No parent: this must itself be the root CapabilityCredential
+            # issued by root_did.
+            if current_claims.get("iss") != root_did:
+                return False
+            if "CapabilityCredential" not in _types_of(current_claims):
+                return False
+            return True
+        if not isinstance(parent_jwt, str):
+            # Phase 1 requires the embedded parent JWT (not a bare jti ref).
+            return False
+        try:
+            parent_claims = verify_vc(parent_jwt, resolver, status_url=status_url)
+        except Exception:
+            return False
+        child_cap = _cap_of(current_claims)
+        parent_cap = _cap_of(parent_claims)
+        if not child_cap or not parent_cap:
+            return False
+        if not _capability_subset(child_cap, parent_cap):
+            return False
+        # The child's issuer must be the subject the parent was delegated to,
+        # i.e. only the holder of the parent VC may sub-delegate.
+        if current_claims.get("iss") != parent_claims.get("sub"):
+            return False
+        current_jwt = parent_jwt
+        current_claims = parent_claims

agentdid/did.py

@@ -0,0 +1,93 @@
+"""DID derivation + DID Document construction (CONTRACTS §12.1).
+
+Two methods are supported:
+
+- ``did:web`` — the **issuer/root** DID (network-resolved, rotatable). Built with
+  :func:`did_for` / :func:`build_did_document`.
+- ``did:key`` — **agent** DIDs (self-certifying, resolved locally; the DID *is* the
+  Ed25519 public key). Built with :func:`did_key_for`. The verificationMethod id is
+  ``<did>#<multibase>`` (did:key convention — the fragment repeats the multibase).
+"""
+from __future__ import annotations
+
+DEFAULT_HOST = "agent-idp.agent-idp.svc"
+
+# The platform/issuer root DID (controller of all agent DIDs).
+ROOT_DID = "did:web:" + DEFAULT_HOST
+
+
+def did_for(name: str, host: str = DEFAULT_HOST) -> str:
+    """Return the agent DID ``did:web:<host>:agents:<name>``."""
+    return f"did:web:{host}:agents:{name}"
+
+
+def did_key_for(pub_multibase: str) -> str:
+    """Return the ``did:key`` for an Ed25519 public key (CONTRACTS §12.1).
+
+    Our ``pub_multibase`` is already the multibase (0xed01-prefixed) Ed25519
+    public key, which is exactly the ``did:key`` identifier, so the DID is simply
+    ``"did:key:" + pub_multibase``.
+    """
+    if not pub_multibase or pub_multibase[0] != "z":
+        raise ValueError("pub_multibase must be a base58btc multibase ('z' prefix)")
+    return "did:key:" + pub_multibase
+
+
+def kid_for(did: str) -> str:
+    """Return the default verificationMethod id (kid) for a DID.
+
+    - ``did:key:z…`` → ``did:key:z…#z…`` (the fragment repeats the multibase,
+      per the did:key convention).
+    - everything else (``did:web``) → ``<did>#key-1``.
+
+    Used by ``issue_vc``/``build_vp``/``respond_challenge`` so the kid in a JWT
+    header (or challenge response) always resolves via ``Resolver.public_key``.
+    """
+    if did.startswith("did:key:"):
+        multibase = did[len("did:key:"):]
+        return f"{did}#{multibase}"
+    return f"{did}#key-1"
+
+
+def build_did_document(
+    did: str,
+    pub_multibase: str,
+    service_endpoint: str,
+    capabilities: list,
+) -> dict:
+    """Build a W3C DID Document per CONTRACTS §12.1.
+
+    - verificationMethod id = ``<did>#key-1`` (Ed25519VerificationKey2020)
+    - authentication + assertionMethod reference that key
+    - one ``AgentService`` service entry
+    - ``metadata.capabilities`` carries the declared capability actions
+    """
+    key_id = f"{did}#key-1"
+    # controller = the issuer/root, unless this DID *is* the root.
+    controller = ROOT_DID if did != ROOT_DID else did
+    return {
+        "@context": [
+            "https://www.w3.org/ns/did/v1",
+            "https://w3id.org/security/suites/ed25519-2020/v1",
+        ],
+        "id": did,
+        "controller": controller,
+        "verificationMethod": [
+            {
+                "id": key_id,
+                "type": "Ed25519VerificationKey2020",
+                "controller": did,
+                "publicKeyMultibase": pub_multibase,
+            }
+        ],
+        "authentication": [key_id],
+        "assertionMethod": [key_id],
+        "service": [
+            {
+                "id": f"{did}#agent",
+                "type": "AgentService",
+                "serviceEndpoint": service_endpoint,
+            }
+        ],
+        "metadata": {"capabilities": list(capabilities)},
+    }

agentdid/keys.py

@@ -0,0 +1,127 @@
+"""Ed25519 keypairs + multibase/multicodec encoding (CONTRACTS §12.2).
+
+Public keys are published in DID Documents as ``publicKeyMultibase`` using the
+W3C ``Ed25519VerificationKey2020`` convention:
+
+    multibase(base58btc, 0xed01 || raw_ed25519_public_key_bytes)
+
+i.e. the 32-byte raw public key is prefixed with the ``ed25519-pub`` multicodec
+varint (0xed 0x01) and the whole thing is base58btc-encoded with a leading ``z``.
+Private keys are returned as plain base64 of the 32-byte raw seed.
+"""
+from __future__ import annotations
+
+import base64
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+# multicodec prefix for an ed25519 public key: 0xed 0x01 (unsigned varint).
+_ED25519_PUB_MULTICODEC = b"\xed\x01"
+
+# --- base58btc (Bitcoin alphabet) -------------------------------------------
+_B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_B58_INDEX = {c: i for i, c in enumerate(_B58_ALPHABET)}
+
+
+def b58encode(data: bytes) -> str:
+    n = int.from_bytes(data, "big")
+    out = ""
+    while n > 0:
+        n, rem = divmod(n, 58)
+        out = _B58_ALPHABET[rem] + out
+    # preserve leading zero bytes as leading '1's
+    pad = 0
+    for b in data:
+        if b == 0:
+            pad += 1
+        else:
+            break
+    return ("1" * pad) + out
+
+
+def b58decode(s: str) -> bytes:
+    n = 0
+    for ch in s:
+        if ch not in _B58_INDEX:
+            raise ValueError(f"invalid base58 character: {ch!r}")
+        n = n * 58 + _B58_INDEX[ch]
+    full = n.to_bytes((n.bit_length() + 7) // 8, "big") if n else b""
+    pad = 0
+    for ch in s:
+        if ch == "1":
+            pad += 1
+        else:
+            break
+    return b"\x00" * pad + full
+
+
+# --- keypair generation ------------------------------------------------------
+def generate_keypair() -> tuple[str, str]:
+    """Generate an Ed25519 keypair.
+
+    Returns ``(priv_b64, pub_multibase)`` where ``priv_b64`` is base64 of the
+    32-byte raw private seed and ``pub_multibase`` is the ``z…`` multibase form.
+    """
+    priv = Ed25519PrivateKey.generate()
+    raw_priv = priv.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    pub_multibase = pub_to_multibase(priv.public_key())
+    return base64.b64encode(raw_priv).decode("ascii"), pub_multibase
+
+
+# --- private key <-> b64 -----------------------------------------------------
+def priv_from_b64(priv_b64: str) -> Ed25519PrivateKey:
+    raw = base64.b64decode(priv_b64)
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def priv_to_b64(priv: Ed25519PrivateKey) -> str:
+    raw = priv.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    return base64.b64encode(raw).decode("ascii")
+
+
+# --- public key <-> multibase ------------------------------------------------
+def pub_to_multibase(pub: Ed25519PublicKey) -> str:
+    raw = pub.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return "z" + b58encode(_ED25519_PUB_MULTICODEC + raw)
+
+
+def multibase_to_pub(pub_multibase: str) -> Ed25519PublicKey:
+    if not pub_multibase or pub_multibase[0] != "z":
+        raise ValueError("publicKeyMultibase must be base58btc ('z' prefix)")
+    decoded = b58decode(pub_multibase[1:])
+    if not decoded.startswith(_ED25519_PUB_MULTICODEC):
+        raise ValueError("not an ed25519-pub multicodec key (expected 0xed01 prefix)")
+    raw = decoded[len(_ED25519_PUB_MULTICODEC):]
+    if len(raw) != 32:
+        raise ValueError(f"expected 32-byte ed25519 key, got {len(raw)}")
+    return Ed25519PublicKey.from_public_bytes(raw)
+
+
+def multibase_to_raw(pub_multibase: str) -> bytes:
+    """Return the raw 32-byte ed25519 public key from a publicKeyMultibase."""
+    pub = multibase_to_pub(pub_multibase)
+    return pub.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def raw_to_multibase(raw: bytes) -> str:
+    if len(raw) != 32:
+        raise ValueError(f"expected 32-byte ed25519 key, got {len(raw)}")
+    return "z" + b58encode(_ED25519_PUB_MULTICODEC + raw)