auth51 0.1.0__py3-none-any.whl

auth51/__init__.py

@@ -0,0 +1,47 @@
+"""
+auth51 — the in-process client (embed mode).
+
+One import installs egress interception (DESIGN §7b: activation = one import).
+It's a no-op until you `configure(...)` an authority + audiences AND wrap agent
+work in `auth51.agent(...)`. Then every governed outbound call carries a scoped,
+verifiable intent token — minted at the source, verified at the resource.
+
+    import auth51
+    auth51.configure(authority_url=..., client_id=..., client_secret=...,
+                     audiences=["api.internal"])
+    with auth51.agent("ReviewBot", checksum=cs, scope="read:repo"):
+        httpx.get("https://api.internal/...")   # ← stamped with an intent token
+"""
+from __future__ import annotations
+
+from .config import Config, configure, get_config, load_env
+from .context import (
+    AgentContext, agent, current, current_derived, effective,
+    workflow, start_workflow, end_workflow, current_workflow, record_step,
+)
+from .identity import Candidate, DerivedIdentity, derive_identity
+from .interceptor import install, uninstall, on_identity_event
+from .obs import observe, current_obs
+from .mcp import (
+    INTENT_META_KEY, build_intent_meta, exchange_intent, extract_intent,
+    incoming_intent, inject_intent, mint_and_inject, mint_for_tool,
+    scope_for_tool, serving,
+)
+from .registry import load_agents, registered_agents, agent_for_checksum, candidates
+
+__all__ = [
+    "Config", "configure", "get_config", "load_env",
+    "AgentContext", "agent", "current", "current_derived", "effective",
+    "workflow", "start_workflow", "end_workflow", "current_workflow", "record_step",
+    "Candidate", "DerivedIdentity", "derive_identity",
+    "install", "uninstall", "on_identity_event",
+    "observe", "current_obs",
+    "INTENT_META_KEY", "build_intent_meta", "extract_intent", "inject_intent",
+    "mint_and_inject", "mint_for_tool", "scope_for_tool",
+    "serving", "incoming_intent", "exchange_intent",
+    "load_agents", "registered_agents", "agent_for_checksum", "candidates",
+]
+
+# Activation = one import. Idempotent; pure passthrough until configured.
+load_env()
+install()

auth51/adapters/langchain.py

@@ -0,0 +1,61 @@
+"""
+LangChain adapter — set the auth51 agent context + record workflow steps at tool
+boundaries, so `import auth51` + this callback handler = governed egress with no
+other app changes. This generalizes the original clientshim's tool wrapper (which
+set the agent contextvar and recorded steps) — minus the framework lock-in and
+the call-stack introspection.
+
+    from langchain.agents import AgentExecutor
+    from auth51.adapters.langchain import Auth51CallbackHandler
+
+    handler = Auth51CallbackHandler(agent_id="ReviewBot", checksum=cs)
+    executor.invoke({...}, config={"callbacks": [handler]})
+
+Import is lazy: this module requires `langchain_core`. The rest of auth51 works
+without it.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "auth51.adapters.langchain requires langchain_core "
+        "(`pip install langchain-core`)."
+    ) from exc
+
+from ..context import AgentContext, _reset_agent, _set_agent, record_step
+
+
+class Auth51CallbackHandler(BaseCallbackHandler):
+    """Binds tool execution to an agent identity for auth51 egress stamping."""
+
+    def __init__(self, agent_id: str, checksum: Optional[str] = None, scope: Optional[str] = None):
+        self.agent_id = agent_id
+        self.checksum = checksum
+        self.scope = scope
+        self._runs: Dict[Any, tuple] = {}   # run_id -> (reset_token, tool_name)
+
+    def on_tool_start(self, serialized: Dict[str, Any], input_str: str, *, run_id=None, **kwargs) -> None:
+        tool = (serialized or {}).get("name") or kwargs.get("name") or ""
+        ctx = AgentContext(
+            agent_id=self.agent_id, checksum=self.checksum,
+            scope=self.scope, tool=tool, provenance="llm-declared",
+        )
+        token = _set_agent(ctx)
+        self._runs[run_id] = (token, tool)
+        record_step(self.agent_id, tool, "started")
+
+    def on_tool_end(self, output: Any, *, run_id=None, **kwargs) -> None:
+        token, tool = self._runs.pop(run_id, (None, ""))
+        record_step(self.agent_id, tool, "completed")
+        if token is not None:
+            _reset_agent(token)
+
+    def on_tool_error(self, error: BaseException, *, run_id=None, **kwargs) -> None:
+        token, tool = self._runs.pop(run_id, (None, ""))
+        record_step(self.agent_id, tool, "failed", error=str(error))
+        if token is not None:
+            _reset_agent(token)

auth51/authority.py

@@ -0,0 +1,241 @@
+"""
+Authority client — mints intent tokens. Uses stdlib urllib (NOT httpx/requests)
+on purpose: those are the libraries the interceptor patches, so minting via them
+would re-enter the interceptor (infinite recursion). urllib sidesteps that
+entirely and keeps the core dependency-free.
+
+Contract mirrors auth51-contracts (the authority OpenAPI): client_credentials →
+OAuth token carrying `generate:intent-token` + delegated scope, then
+POST /v1/intent/token with grant_type=agent_checksum.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+import urllib.request
+from typing import Dict, Optional, Tuple
+
+from .config import get_config
+
+
+class AuthorityError(Exception):
+    pass
+
+
+# OAuth client_credentials tokens cached per scope-set (mirrors the proxy).
+_oauth_cache: Dict[str, Tuple[str, float]] = {}
+
+
+def _post_form(url: str, data: dict, headers: Optional[dict] = None) -> dict:
+    body = urllib.parse.urlencode(data).encode()
+    req = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={"content-type": "application/x-www-form-urlencoded", **(headers or {})},
+    )
+    with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310 (trusted authority URL)
+        return json.loads(r.read().decode())
+
+
+def _post_json(url: str, obj: dict, headers: Optional[dict] = None) -> dict:
+    body = json.dumps(obj).encode()
+    req = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={"content-type": "application/json", **(headers or {})},
+    )
+    with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310
+        return json.loads(r.read().decode())
+
+
+def get_json(url: str, headers: Optional[dict] = None) -> dict:
+    req = urllib.request.Request(url, method="GET", headers=headers or {})
+    with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310
+        return json.loads(r.read().decode())
+
+
+def get_oauth_token(full_scope: str) -> str:
+    """An auth51 OAuth token for an exact scope string, cached per scope-set.
+
+    Keyed path (on-prem / local / anywhere with a secret): client_credentials
+    using the configured client_id/client_secret. Keyless path (cloud): if no
+    secret is configured, prove the runtime's ambient workload identity (AWS
+    today) and let the authority mint — no stored secret. See
+    DESIGN-keyless-workload-identity.md."""
+    cfg = get_config()
+    now = time.time()
+    cached = _oauth_cache.get(full_scope)
+    if cached and now < cached[1] - 5:
+        return cached[0]
+    if cfg.client_id and cfg.client_secret:
+        data = _post_form(
+            cfg.authority_url.rstrip("/") + "/v1/oauth/token",
+            {
+                "grant_type": "client_credentials",
+                "client_id": cfg.client_id,
+                "client_secret": cfg.client_secret,
+                "scope": full_scope,
+            },
+        )
+    else:
+        data = _acquire_workload_token(full_scope)
+    tok = data.get("access_token")
+    if not tok:
+        raise AuthorityError("OAuth token endpoint returned no access_token")
+    _oauth_cache[full_scope] = (tok, now + float(data.get("expires_in", 300)))
+    return tok
+
+
+def _acquire_workload_token(full_scope: str) -> dict:
+    """Keyless: sign an ambient AWS identity proof and exchange it for an auth51
+    token at /workload/aws-token. The issued token is DPoP-bound to our PoP key,
+    so a replayed GetCallerIdentity would yield a token the replayer can't use."""
+    from . import aws, pop  # local imports: keep authority import-light
+
+    cfg = get_config()
+    cnf = pop.jkt() if cfg.pop_enabled else None
+    payload = aws.signed_identity_payload(cnf_jkt=cnf)
+    if payload is None:
+        raise AuthorityError(
+            "no auth51 credentials: set AUTH51_CLIENT_ID/SECRET, or run on a "
+            "registered cloud workload identity (AWS role)."
+        )
+    payload["scope"] = full_scope
+    return _post_json(cfg.authority_url.rstrip("/") + "/v1/workload/aws-token", payload)
+
+
+def mint_intent(
+    *,
+    agent_id: str,
+    checksum: Optional[str],
+    scope: str,
+    audience: str,
+    workflow_id: Optional[str] = None,
+    workflow_step: Optional[dict] = None,
+    delegation_context: Optional[dict] = None,
+    cnf_jkt: Optional[str] = None,
+) -> str:
+    """
+    Mint a scoped, short-lived intent token for one agent action (Hop A).
+    Optional workflow_id/step/delegation_context ride in for provenance (§4.3);
+    workflow_enabled stays False (we don't use the authority's DAG authz path).
+    cnf_jkt binds the token to the caller's ephemeral PoP key (DPoP / RFC 9449).
+    """
+    cfg = get_config()
+    # The OAuth client_credentials token only needs the mint capability
+    # (generate:intent-token). The delegated scope goes in the mint body's
+    # requested_scopes and is governed by the agent GRANT — NOT the OAuth token
+    # (the authority does not require requested ⊆ OAuth scopes; the grant is the
+    # ceiling). Folding the delegated scope into the OAuth request would 400 for
+    # any scope this OAuth client isn't explicitly granted.
+    oauth = get_oauth_token("generate:intent-token")
+    payload = {
+        "grant_type": "agent_checksum",
+        "agent_id": agent_id,
+        "computed_checksum": checksum or "",
+        "requested_scopes": scope.split() if scope else [],
+        "audience": audience,
+        "workflow_enabled": False,
+    }
+    if workflow_id:
+        payload["workflow_id"] = workflow_id
+    if workflow_step:
+        payload["workflow_step"] = workflow_step
+    if delegation_context:
+        payload["delegation_context"] = delegation_context
+    if cnf_jkt:
+        payload["cnf_jkt"] = cnf_jkt
+    mint_url = cfg.authority_url.rstrip("/") + "/v1/intent/token"
+    data = _post_json(mint_url, payload, headers={"authorization": f"Bearer {oauth}"})
+    tok = data.get("access_token")
+    if not tok:
+        raise AuthorityError("intent mint returned no access_token")
+    # Record the exchange for the live viewer (observability). The Authorization
+    # bearer is intentionally omitted (it's a client-credentials secret-equivalent);
+    # the request body + response are the transparency-relevant parts.
+    global _last_mint_exchange
+    _last_mint_exchange = {
+        "request": {"method": "POST", "url": mint_url, "body": payload},
+        "response": data,
+    }
+    return tok
+
+
+_last_mint_exchange: Optional[dict] = None
+
+
+def last_mint_exchange() -> Optional[dict]:
+    """The most recent mint request/response (for the live viewer). Per-process,
+    overwritten each mint; never includes the OAuth bearer."""
+    return _last_mint_exchange
+
+
+_JWT_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:jwt"
+_TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
+
+
+def exchange_token(
+    subject_token: str, *, audience: str, scope: Optional[str] = None
+) -> str:
+    """Hop B (RFC 8693): exchange an intent token (subject) for a downstream
+    token scoped/audienced for the RS. Used at an MCP server's egress. The
+    authority verifies the subject_token against its trusted-issuer config —
+    so the authority must trust its own issuer for self-issued intent tokens.
+    """
+    cfg = get_config()
+    data = {
+        "grant_type": _TOKEN_EXCHANGE_GRANT,
+        "subject_token": subject_token,
+        "subject_token_type": _JWT_TOKEN_TYPE,
+        "audience": audience,
+    }
+    if scope:
+        data["scope"] = scope
+    out = _post_form(cfg.authority_url.rstrip("/") + "/v1/oauth/token", data)
+    tok = out.get("access_token")
+    if not tok:
+        raise AuthorityError("token exchange returned no access_token")
+    return tok
+
+
+def exchange_session(
+    session_token: str,
+    *,
+    audience: str,
+    scope: Optional[str] = None,
+    bind_pop: bool = True,
+) -> str:
+    """Exchange an EXTERNAL session token — issued by the application's own IDP
+    (a trusted issuer registered at the authority: Okta/Auth0/Entra/the legacy
+    patchet IDP/…) — for a sender-constrained auth51 OAuth token (RFC 8693).
+
+    Two properties close the A2 gap (a stolen session token being enough):
+      * we authenticate with the embed's CLIENT credential, so the session token
+        alone cannot be exchanged (the issuer is marked require_client_auth);
+      * the issued token is DPoP-bound to the ephemeral PoP key (cnf.jkt), so it
+        cannot be replayed — the same key then proves possession when this token
+        mints intent tokens.
+    The returned token is the auth51 OAuth token used in place of a raw external
+    session for `generate:intent-token`.
+    """
+    from . import pop  # local import: pop has no dep on authority, avoid cycle
+
+    cfg = get_config()
+    data = {
+        "grant_type": _TOKEN_EXCHANGE_GRANT,
+        "subject_token": session_token,
+        "subject_token_type": _JWT_TOKEN_TYPE,
+        "audience": audience,
+        "client_id": cfg.client_id or "",
+        "client_secret": cfg.client_secret or "",
+    }
+    if scope:
+        data["scope"] = scope
+    if bind_pop:
+        jkt = pop.jkt()
+        if jkt:
+            data["cnf_jkt"] = jkt
+    out = _post_form(cfg.authority_url.rstrip("/") + "/v1/oauth/token", data)
+    tok = out.get("access_token")
+    if not tok:
+        raise AuthorityError("session exchange returned no access_token")
+    return tok

auth51/aws.py

@@ -0,0 +1,155 @@
+"""
+Ambient AWS identity → a signed sts:GetCallerIdentity payload for the authority's
+keyless `/workload/aws-token` endpoint. No boto3: credential discovery + SigV4 are
+pure stdlib, so the embed stays dependency-light.
+
+Discovery order (matches how the AWS SDK resolves a workload's role):
+  1. env    — AWS_ACCESS_KEY_ID / _SECRET_ACCESS_KEY / _SESSION_TOKEN
+  2. ECS    — the container credentials endpoint (Fargate / ECS task role)
+  3. EC2    — IMDSv2 instance-profile role
+
+The signed request proves the STABLE role behind these temp creds (STS returns the
+role ARN); the ephemeral keys never leave the process except as a signature AWS
+itself validates. See DESIGN-keyless-workload-identity.md §2.
+"""
+from __future__ import annotations
+
+import base64
+import datetime as _dt
+import hashlib
+import hmac
+import json
+import os
+import urllib.request
+from dataclasses import dataclass
+from typing import Optional
+
+# Must equal the authority's AUTH51_AWS_SERVER_ID — binds the signature to auth51
+# so a GetCallerIdentity signed for us can't be replayed elsewhere (and vice versa).
+SERVER_ID = os.getenv("AUTH51_AWS_SERVER_ID", "authority.auth51.com")
+SERVER_ID_HEADER = "X-Auth51-Server-Id"
+_IMDS = "http://169.254.169.254"
+_ECS_HOST = "http://169.254.170.2"
+
+
+@dataclass
+class _Creds:
+    access_key: str
+    secret_key: str
+    token: Optional[str]
+
+
+def _get(url: str, headers: Optional[dict] = None, method: str = "GET", timeout: float = 1.0):
+    req = urllib.request.Request(url, headers=headers or {}, method=method)
+    with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (link-local)
+        return r.read().decode()
+
+
+def discover_credentials() -> Optional[_Creds]:
+    """Return ambient AWS creds, or None if this isn't running on AWS."""
+    ak, sk = os.getenv("AWS_ACCESS_KEY_ID"), os.getenv("AWS_SECRET_ACCESS_KEY")
+    if ak and sk:
+        return _Creds(ak, sk, os.getenv("AWS_SESSION_TOKEN"))
+
+    # ECS / Fargate task role — the SDK's container credentials provider.
+    rel = os.getenv("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI")
+    full = os.getenv("AWS_CONTAINER_CREDENTIALS_FULL_URI")
+    try:
+        if rel or full:
+            url = full or (_ECS_HOST + rel)
+            hdr = {}
+            tok_file = os.getenv("AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE")
+            if tok_file and os.path.exists(tok_file):
+                with open(tok_file) as f:
+                    hdr["Authorization"] = f.read().strip()
+            d = json.loads(_get(url, headers=hdr, timeout=2.0))
+            return _Creds(d["AccessKeyId"], d["SecretAccessKey"], d.get("Token"))
+    except Exception:  # noqa: BLE001 — fall through to IMDS / None
+        pass
+
+    # EC2 IMDSv2 instance profile.
+    try:
+        token = _get(_IMDS + "/latest/api/token", method="PUT",
+                     headers={"X-aws-ec2-metadata-token-ttl-seconds": "60"})
+        h = {"X-aws-ec2-metadata-token": token}
+        base = _IMDS + "/latest/meta-data/iam/security-credentials/"
+        role = _get(base, headers=h).strip().splitlines()[0]
+        d = json.loads(_get(base + role, headers=h))
+        return _Creds(d["AccessKeyId"], d["SecretAccessKey"], d.get("Token"))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _sign(key: bytes, msg: str) -> bytes:
+    return hmac.new(key, msg.encode(), hashlib.sha256).digest()
+
+
+def signed_identity_payload(cnf_jkt: Optional[str] = None) -> Optional[dict]:
+    """Build the SigV4-signed GetCallerIdentity payload for /workload/aws-token,
+    or None if no ambient AWS identity is available. `cnf_jkt` (the DPoP key
+    thumbprint) is passed through so the issued token is sender-constrained."""
+    creds = discover_credentials()
+    if creds is None:
+        return None
+
+    region = os.getenv("AWS_REGION") or os.getenv("AWS_DEFAULT_REGION") or "us-east-1"
+    host = f"sts.{region}.amazonaws.com"
+    body = "Action=GetCallerIdentity&Version=2011-06-15"
+    now = _dt.datetime.now(_dt.timezone.utc)
+    amzdate = now.strftime("%Y%m%dT%H%M%SZ")
+    datestamp = now.strftime("%Y%m%d")
+
+    # Canonical headers — sorted, lowercased. x-auth51-server-id MUST be signed.
+    headers = {
+        "content-type": "application/x-www-form-urlencoded; charset=utf-8",
+        "host": host,
+        "x-amz-date": amzdate,
+        SERVER_ID_HEADER.lower(): SERVER_ID,
+    }
+    if creds.token:
+        headers["x-amz-security-token"] = creds.token
+    signed_keys = sorted(headers)
+    canonical_headers = "".join(f"{k}:{headers[k]}\n" for k in signed_keys)
+    signed_headers = ";".join(signed_keys)
+    payload_hash = hashlib.sha256(body.encode()).hexdigest()
+    canonical_request = (
+        f"POST\n/\n\n{canonical_headers}\n{signed_headers}\n{payload_hash}"
+    )
+
+    scope = f"{datestamp}/{region}/sts/aws4_request"
+    string_to_sign = (
+        "AWS4-HMAC-SHA256\n" + amzdate + "\n" + scope + "\n"
+        + hashlib.sha256(canonical_request.encode()).hexdigest()
+    )
+    k_date = _sign(("AWS4" + creds.secret_key).encode(), datestamp)
+    k_region = _sign(k_date, region)
+    k_service = _sign(k_region, "sts")
+    k_signing = _sign(k_service, "aws4_request")
+    signature = hmac.new(k_signing, string_to_sign.encode(), hashlib.sha256).hexdigest()
+    authorization = (
+        f"AWS4-HMAC-SHA256 Credential={creds.access_key}/{scope}, "
+        f"SignedHeaders={signed_headers}, Signature={signature}"
+    )
+
+    wire_headers = {
+        "Authorization": authorization,
+        "X-Amz-Date": amzdate,
+        SERVER_ID_HEADER: SERVER_ID,
+        "Host": host,
+        "Content-Type": headers["content-type"],
+    }
+    if creds.token:
+        wire_headers["X-Amz-Security-Token"] = creds.token
+
+    def _b64(s: str) -> str:
+        return base64.b64encode(s.encode()).decode()
+
+    out = {
+        "iam_http_request_method": "POST",
+        "iam_request_url": _b64(f"https://{host}/"),
+        "iam_request_body": _b64(body),
+        "iam_request_headers": _b64(json.dumps(wire_headers)),
+    }
+    if cnf_jkt:
+        out["cnf_jkt"] = cnf_jkt
+    return out

auth51/config.py

@@ -0,0 +1,59 @@
+"""Configuration for the embed client. Set via auth51.configure(...) or env."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional, Set
+
+
+@dataclass
+class Config:
+    # Defaults to the managed SaaS authority; override only for self-hosted.
+    authority_url: Optional[str] = "https://authority.auth51.com"
+    app_id: Optional[str] = None          # for load_agents() startup-sync
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    # Destination hosts to govern. Egress to a host NOT in this set is passed
+    # through untouched — so an unconfigured client is a pure no-op.
+    audiences: Set[str] = field(default_factory=set)
+    header: str = "Authorization"
+    scheme: str = "Bearer"
+    # Fail-CLOSED by default: if minting fails, BLOCK the egress rather than
+    # forward it unauthenticated. This is the safe posture (and what high-assurance
+    # deployments expect). Set True (or AUTH51_FAIL_OPEN=1) to fail-open — forward
+    # untokenized on mint failure — only where availability must trump enforcement.
+    fail_open: bool = False
+    # Proof-of-Possession (DPoP / RFC 9449): bind tokens to an ephemeral key and
+    # attach a per-request proof. No-op if `cryptography`+`pyjwt` aren't installed.
+    pop_enabled: bool = True
+
+
+_config = Config()
+
+
+def configure(**kwargs) -> Config:
+    for k, v in kwargs.items():
+        if not hasattr(_config, k):
+            raise AttributeError(f"unknown config key: {k}")
+        setattr(_config, k, set(v) if k == "audiences" else v)
+    return _config
+
+
+def get_config() -> Config:
+    return _config
+
+
+def load_env() -> Config:
+    _config.authority_url = os.getenv("AUTH51_AUTHORITY_URL", _config.authority_url)
+    _config.client_id = os.getenv("AUTH51_CLIENT_ID", _config.client_id)
+    _config.client_secret = os.getenv("AUTH51_CLIENT_SECRET", _config.client_secret)
+    aud = os.getenv("AUTH51_AUDIENCES")
+    if aud:
+        _config.audiences = {a.strip() for a in aud.split(",") if a.strip()}
+    fo = os.getenv("AUTH51_FAIL_OPEN")
+    if fo is not None:
+        _config.fail_open = fo.strip().lower() not in ("0", "false", "no")
+    pe = os.getenv("AUTH51_POP_ENABLED")
+    if pe is not None:
+        _config.pop_enabled = pe.strip().lower() not in ("0", "false", "no")
+    return _config