hearth-sdk 1.0.0__tar.gz

hearth_sdk-1.0.0/.gitignore

@@ -0,0 +1,75 @@
+# Rust build artifacts
+/target/
+**/*.rs.bk
+.env
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Coverage
+lcov.info
+*.profraw
+
+# Fuzz artifacts
+fuzz/artifacts/
+fuzz/corpus/
+
+# Proptest regressions
+**/proptest-regressions/
+
+node_modules/
+.reflex/
+
+# Tailwind standalone CLI (binary, not committed — install via `make tailwind-install`)
+ui/tailwindcss
+
+# Generated protobuf code (produced by build.rs on every build)
+/src/protocol/generated/
+
+# Binary symlink at repo root (not the helm chart subdirectory)
+/hearth
+*.wal
+
+# Local runtime data (compose named volume + `cargo run` default path)
+/data/
+
+*.jpg
+*.jpeg
+*.png
+*.log
+
+.playwright-mcp/
+
+/hearth.yaml
+/hearth.yml
+
+.codex
+
+# Backup files
+*.bak
+
+# UI test artifacts (generated by make ui-test-smoke)
+tests/ui/.auth/
+tests/ui/reports/
+tests/ui/node_modules/
+
+*.tsbuildinfo
+**/.phpunit.cache
+
+**/.next/*
+.next
+
+go-gin
+
+**/php/vendor
+*.cache
+
+.claude/scheduled_tasks.lock

hearth_sdk-1.0.0/.releaserc.json

@@ -0,0 +1,17 @@
+{
+  "branches": [
+    "main",
+    { "name": "1.x", "range": "1.x.x", "channel": "1.x" },
+    { "name": "2.x", "range": "2.x.x", "channel": "2.x" }
+  ],
+  "tagFormat": "sdk-python-v${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    ["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
+    ["@semantic-release/exec", {
+      "prepareCmd": "sed -i 's/^version = \"[^\"]*\"/version = \"${nextRelease.version}\"/' pyproject.toml"
+    }],
+    ["@semantic-release/github", { "successComment": false, "failComment": false }]
+  ]
+}

hearth_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `hearth-python` are documented here.
+
+## [Unreleased]
+
+### Added
+- **`client.check_permission(access_token, permission, **opts)`** — calls `POST /oauth/authorize`
+  for a live per-request permission decision (decision mode). Fail-closed: any network or server
+  error returns `CheckPermissionResponse(allowed=False)` rather than raising (HEA-926).
+- **`client.introspect(access_token, client_id, **opts)`** — calls RFC 7662
+  `POST /realms/{realm_id}/introspect`. Response includes a `mode` field that middleware
+  MUST validate against the configured expected mode (HEA-926).
+- **`RequirePermissionMiddleware`** — ASGI middleware (Starlette, FastAPI) that enforces
+  a named permission using an explicit `mode`. Never auto-detects mode from JWT claim
+  presence (HEA-926 design constraint).
+- **`WsgiPermissionMiddleware`** — WSGI middleware (Flask, Django) with identical
+  mode-awareness contract (HEA-926).
+- **`AuthorizationModeMismatchError`** — raised when the introspection response echoes a
+  mode that differs from the configured expectation; middleware maps this to a 403 denial.
+- **`AccessTokenAuthorizationMode`** type alias (`Literal["embedded", "introspection", "decision"]`).
+- **`IntrospectRequest`**, **`IntrospectResponse`**, **`CheckPermissionRequest`**,
+  **`CheckPermissionResponse`** Pydantic models.
+
+### Changed
+- SDK brought into conformance with the [Hearth SDK Common Specification](../../docs/specs/SDK.md).
+- All 9 required error types from spec §5 are now exported.
+- Full Claims API (spec §4) implemented on verified token objects.
+- JWKS caching follows the 5-rule contract from spec §2.
+- README updated with installation, quickstart, and troubleshooting sections (spec §10).

hearth_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: hearth-sdk
+Version: 1.0.0
+Summary: Hearth identity platform Python SDK
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: pyjwt[crypto]>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'

hearth_sdk-1.0.0/README.md

@@ -0,0 +1,182 @@
+# Hearth Python SDK
+
+Python client for the [Hearth](https://github.com/hearth-auth/hearth) identity API.
+
+> **SDK Specification:** This SDK must conform to the [Hearth SDK Common Specification](../../docs/specs/SDK.md).
+
+## Installation
+
+```bash
+pip install hearth-sdk
+```
+
+## Quick start
+
+```python
+from hearth import HearthClient
+
+client = HearthClient(
+    issuer_url="https://hearth.example.com",
+    client_id="<your-client-id>",
+)
+```
+
+## Permission delivery modes
+
+Hearth supports three permission delivery modes controlled by the `access_token_authorization`
+field on the OAuth client registration. The Python SDK exposes all three via explicit middleware
+and client methods. **Mode is always configured explicitly — the SDK never auto-detects it from
+JWT claim presence.**
+
+### embedded (default)
+
+Permissions are embedded in the JWT at issuance. No network call on the hot path.
+
+```python
+from hearth.middleware import WsgiPermissionMiddleware
+
+# Flask example
+app.wsgi_app = WsgiPermissionMiddleware(
+    app.wsgi_app,
+    client=client,
+    permission="docs.write",
+    mode="embedded",
+)
+```
+
+### decision
+
+The server makes a live per-request decision via `POST /oauth/authorize`. Fail-closed on errors.
+
+```python
+# Starlette / FastAPI example
+from hearth.middleware import RequirePermissionMiddleware
+
+app = RequirePermissionMiddleware(
+    app,
+    client=client,
+    permission="docs.write",
+    mode="decision",
+)
+```
+
+Or call directly (returns `CheckPermissionResponse(allowed=False)` on any error):
+
+```python
+result = client.check_permission(access_token, "docs.write")
+if not result.allowed:
+    raise PermissionError("forbidden")
+```
+
+### introspection
+
+The server introspects the token live via `POST /realms/{realm_id}/introspect` (RFC 7662).
+The response echoes a `mode` field; middleware rejects tokens whose echoed mode does not
+match the configured expectation.
+
+```python
+from hearth.middleware import RequirePermissionMiddleware
+
+app = RequirePermissionMiddleware(
+    app,
+    client=client,
+    permission="docs.write",
+    mode="introspection",
+    client_id="<resource-server-client-id>",
+    client_secret="<secret>",   # optional for public clients
+)
+```
+
+Or call directly:
+
+```python
+from hearth.errors import AuthorizationModeMismatchError
+
+resp = client.introspect(access_token, client_id="<cid>", client_secret="<sec>")
+if not resp.active:
+    raise PermissionError("inactive token")
+if resp.mode != "introspection":
+    raise AuthorizationModeMismatchError("introspection", resp.mode or "embedded")
+if "docs.write" not in (resp.permissions or []):
+    raise PermissionError("forbidden")
+```
+
+## Troubleshooting
+
+**`DiscoveryError`** — verify `issuer_url` is reachable and returns a valid `/.well-known/openid-configuration`.
+
+**`JWKSFetchError`** — check network connectivity to the JWKS endpoint. The SDK retries once on a cache miss before returning this error.
+
+**`TokenExpiredError`** — the token's `exp` claim is in the past. Refresh the token or re-authenticate.
+
+**`TokenInvalidError`** — JWT signature does not match any key in the JWKS. If the server recently rotated keys the SDK will re-fetch once automatically; persistent failures indicate a key mismatch.
+
+**`TokenAudienceError`** — the token's `aud` claim does not contain the configured audience. Verify `client_id` matches the audience your authorization server issues.
+
+See [docs/specs/SDK.md](../../docs/specs/SDK.md) Section 5 for the full error taxonomy.
+
+---
+
+## Agent Authentication (M5)
+
+Enable `agent_auth.capabilities.identity = true` (plus `advanced = true` for AATs/transaction tokens) in `hearth.yaml`.
+
+```python
+import httpx, hashlib, json, base64, time, uuid
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature
+
+# ── DPoP proof (RFC 9449) ──────────────────────────────────────────────────
+priv = ec.generate_private_key(ec.SECP256R1())
+pub = priv.public_key().public_bytes(
+    serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo
+)
+pub_numbers = priv.public_key().public_numbers()
+x = base64.urlsafe_b64encode(pub_numbers.x.to_bytes(32, "big")).rstrip(b"=").decode()
+y = base64.urlsafe_b64encode(pub_numbers.y.to_bytes(32, "big")).rstrip(b"=").decode()
+
+canonical = json.dumps({"crv": "P-256", "kty": "EC", "x": x, "y": y}, separators=(",", ":"))
+thumbprint = base64.urlsafe_b64encode(hashlib.sha256(canonical.encode()).digest()).rstrip(b"=").decode()
+
+def b64u(obj):
+    return base64.urlsafe_b64encode(json.dumps(obj).encode()).rstrip(b"=").decode()
+
+def make_dpop_proof(htm: str, htu: str, nonce: str | None = None) -> str:
+    header = {"alg": "ES256", "jwk": {"crv": "EC", "kty": "EC", "x": x, "y": y}, "typ": "dpop+jwt"}
+    claims = {"htm": htm, "htu": htu, "iat": int(time.time()), "jti": str(uuid.uuid4())}
+    if nonce:
+        claims["nonce"] = nonce
+    signing_input = f"{b64u(header)}.{b64u(claims)}"
+    der_sig = priv.sign(signing_input.encode(), ec.ECDSA(hashes.SHA256()))
+    r, s = decode_dss_signature(der_sig)  # convert DER → raw r||s for JWT
+    raw_sig = r.to_bytes(32, "big") + s.to_bytes(32, "big")
+    return f"{signing_input}.{base64.urlsafe_b64encode(raw_sig).rstrip(b'=').decode()}"
+
+# ── client_credentials + DPoP ─────────────────────────────────────────────
+token_url = f"{base_url}/realms/{realm_id}/token"
+resp = httpx.post(token_url, data={"grant_type": "client_credentials"}, auth=(client_id, secret),
+                  headers={"DPoP": make_dpop_proof("POST", token_url)})
+nonce = resp.headers.get("dpop-nonce")
+resp = httpx.post(token_url, data={"grant_type": "client_credentials"}, auth=(client_id, secret),
+                  headers={"DPoP": make_dpop_proof("POST", token_url, nonce)})
+access_token = resp.json()["access_token"]
+# Decoded JWT claims will contain: cnf.jkt == thumbprint
+
+# ── AAT (admin token required for /v1/aats) ────────────────────────────────
+root_aat = httpx.post(f"{base_url}/v1/aats", json={
+    "realm_id": realm_id, "agent_id": agent_id,
+    "tools": [{"tool_name": "read_docs", "constraints": None}],
+    "expires_in_secs": 3600,
+}, headers={"Authorization": f"Bearer {admin_token}"}).json()
+
+# ── Transaction token ──────────────────────────────────────────────────────
+txn = httpx.post(f"{base_url}/v1/transaction-tokens", json={
+    "realm_id": realm_id,
+    "requesting_agent_id": agent_a_id,
+    "target_agent_id": agent_b_id,
+    "txn_id": f"txn-{uuid.uuid4()}",
+}, headers={"Authorization": f"Bearer {admin_token}"}).json()
+```
+
+For the full surface (draft tracking, RFC 8693 exchange, Agent Card), see the [TypeScript SDK README](../typescript/README.md#agent-authentication-m5).

hearth_sdk-1.0.0/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@hearth-auth/sdk-python",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Hearth Python SDK — package.json shim for multi-semantic-release"
+}

hearth_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "hearth-sdk"
+version = "1.0.0"
+description = "Hearth identity platform Python SDK"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pyjwt[crypto]>=2.8",
+    "pydantic>=2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hearth"]

hearth_sdk-1.0.0/src/hearth/__init__.py

@@ -0,0 +1,113 @@
+"""Hearth identity platform Python SDK.
+
+Provides HearthClient (auth flows, RBAC predicates), AdminClient
+(user/realm CRUD), mode-aware middleware, and all request/response types.
+"""
+
+from .client import HearthClient
+from .admin import AdminClient
+from .errors import (
+    HearthError,
+    HearthSdkError,
+    ConfigurationError,
+    DiscoveryError,
+    JWKSFetchError,
+    TokenExpiredError,
+    TokenNotYetValidError,
+    TokenInvalidError,
+    TokenIssuerError,
+    TokenAudienceError,
+    IntrospectionError,
+    RequiredActionError,
+    AuthorizationModeMismatchError,
+)
+from .claims import Claims
+from .middleware import RequirePermissionMiddleware, WsgiPermissionMiddleware
+from .types import (
+    AccessTokenAuthorizationMode,
+    BootstrapResponse,
+    User,
+    CreateUserRequest,
+    UpdateUserRequest,
+    Realm,
+    CreateRealmRequest,
+    UpdateRealmRequest,
+    PageResponse,
+    AuthorizeResponse,
+    TokenResponse,
+    UserInfoResponse,
+    MePermissionsResponse,
+    OAuthClient,
+    RegisterClientRequest,
+    CreateClientRequest,
+    UpdateClientRequest,
+    Role,
+    CreateRoleRequest,
+    UpdateRoleRequest,
+    Group,
+    CreateGroupRequest,
+    UpdateGroupRequest,
+    OrgMember,
+    AddOrgMemberRequest,
+    JwksDocument,
+    IntrospectRequest,
+    IntrospectResponse,
+    CheckPermissionRequest,
+    CheckPermissionResponse,
+)
+
+__all__ = [
+    # Clients
+    "HearthClient",
+    "AdminClient",
+    # Middleware
+    "RequirePermissionMiddleware",
+    "WsgiPermissionMiddleware",
+    # Errors
+    "HearthError",
+    "HearthSdkError",
+    "ConfigurationError",
+    "DiscoveryError",
+    "JWKSFetchError",
+    "TokenExpiredError",
+    "TokenNotYetValidError",
+    "TokenInvalidError",
+    "TokenIssuerError",
+    "TokenAudienceError",
+    "IntrospectionError",
+    "RequiredActionError",
+    "AuthorizationModeMismatchError",
+    # Claims
+    "Claims",
+    # Types
+    "AccessTokenAuthorizationMode",
+    "BootstrapResponse",
+    "User",
+    "CreateUserRequest",
+    "UpdateUserRequest",
+    "Realm",
+    "CreateRealmRequest",
+    "UpdateRealmRequest",
+    "PageResponse",
+    "AuthorizeResponse",
+    "TokenResponse",
+    "UserInfoResponse",
+    "MePermissionsResponse",
+    "OAuthClient",
+    "RegisterClientRequest",
+    "CreateClientRequest",
+    "UpdateClientRequest",
+    "Role",
+    "CreateRoleRequest",
+    "UpdateRoleRequest",
+    "Group",
+    "CreateGroupRequest",
+    "UpdateGroupRequest",
+    "OrgMember",
+    "AddOrgMemberRequest",
+    "JwksDocument",
+    "IntrospectRequest",
+    "IntrospectResponse",
+    "CheckPermissionRequest",
+    "CheckPermissionResponse",
+]